This is tar.info, produced by Makeinfo version 3.12f from tar.texi.
START-INFO-DIR-ENTRY
* tar: (tar). Making tape (or disk) archives.
END-INFO-DIR-ENTRY
This file documents GNU `tar', a utility used to store, backup, and
transport files.
Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
This file documents GNU `tar', which is a utility used to store,
backup, and transport files. `tar' is a tape (or disk) archiver. This
manual documents the release 1.13.
File: tar.info, Node: Full Dumps, Next: Inc Dumps, Prev: Backups, Up: Backups
Using `tar' to Perform Full Dumps
=================================
_(This message will disappear, once this node revised.)_
Full dumps should only be made when no other people or programs are
modifying files in the filesystem. If files are modified while `tar'
is making the backup, they may not be stored properly in the archive,
in which case you won't be able to restore them if you have to. (Files
not being modified are written with no trouble, and do not corrupt the
entire archive.)
You will want to use the `--label=ARCHIVE-LABEL' (`-V
ARCHIVE-LABEL') option to give the archive a volume label, so you can
tell what this archive is even if the label falls off the tape, or
anything like that.
Unless the filesystem you are dumping is guaranteed to fit on one
volume, you will need to use the `--multi-volume' (`-M') option. Make
sure you have enough tapes on hand to complete the backup.
If you want to dump each filesystem separately you will need to use
the `--one-file-system' (`-l') option to prevent `tar' from crossing
filesystem boundaries when storing (sub)directories.
The `--incremental' (`-G') option is not needed, since this is a
complete copy of everything in the filesystem, and a full restore from
this backup would only be done onto a completely empty disk.
Unless you are in a hurry, and trust the `tar' program (and your
tapes), it is a good idea to use the `--verify' (`-W') option, to make
sure your files really made it onto the dump properly. This will also
detect cases where the file was modified while (or just after) it was
being archived. Not all media (notably cartridge tapes) are capable of
being verified, unfortunately.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') take a
file name argument always. If the file doesn't exist, run a level zero
dump, creating the file. If the file exists, uses that file to see
what has changed.
`--incremental' (`-G')
`--incremental' (`-G') handle old GNU-format incremental backup.
This option should only be used when creating an incremental backup
of a filesystem. When the `--incremental' (`-G') option is used, `tar'
writes, at the beginning of the archive, an entry for each of the
directories that will be operated on. The entry for a directory
includes a list of all the files in the directory at the time the dump
was done, and a flag for each file indicating whether the file is going
to be put in the archive. This information is used when doing a
complete incremental restore.
Note that this option causes `tar' to create a non-standard archive
that may not be readable by non-GNU versions of the `tar' program.
The `--incremental' (`-G') option means the archive is an incremental
backup. Its meaning depends on the command that it modifies.
If the `--incremental' (`-G') option is used with `--list' (`-t'),
`tar' will list, for each directory in the archive, the list of files in
that directory at the time the archive was created. This information
is put out in a format that is not easy for humans to read, but which
is unambiguous for a program: each file name is preceded by either a
`Y' if the file is present in the archive, an `N' if the file is not
included in the archive, or a `D' if the file is a directory (and is
included in the archive). Each file name is terminated by a null
character. The last file is followed by an additional null and a
newline to indicate the end of the data.
If the `--incremental' (`-G') option is used with `--extract'
(`--get', `-x'), then when the entry for a directory is found, all
files that currently exist in that directory but are not listed in the
archive _are deleted from the directory_.
This behavior is convenient when you are restoring a damaged file
system from a succession of incremental backups: it restores the entire
state of the file system to that which obtained when the backup was
made. If you don't use `--incremental' (`-G'), the file system will
probably fill up with files that shouldn't exist any more.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') handle new
GNU-format incremental backup. This option handles new GNU-format
incremental backup. It has much the same effect as `--incremental'
(`-G'), but also the time when the dump is done and the list of
directories dumped is written to the given FILE. When restoring, only
files newer than the saved time are restored, and the direcotyr list is
used to speed up operations.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') acts like
`--incremental' (`-G'), but when used in conjunction with `--create'
(`-c') will also cause `tar' to use the file FILE, which contains
information about the state of the filesystem at the time of the last
backup, to decide which files to include in the archive being created.
That file will then be updated by `tar'. If the file FILE does not
exist when this option is specified, `tar' will create it, and include
all appropriate files in the archive.
The file, which is archive independent, contains the date it was last
modified and a list of devices, inode numbers and directory names.
`tar' will archive files with newer mod dates or inode change times,
and directories with an unchanged inode number and device but a changed
directory name. The file is updated after the files to be archived are
determined, but before the new archive is actually created.
GNU `tar' actually writes the file twice: once before the data and
written, and once after.
File: tar.info, Node: Inc Dumps, Next: incremental and listed-incremental, Prev: Full Dumps, Up: Backups
Using `tar' to Perform Incremental Dumps
========================================
_(This message will disappear, once this node revised.)_
Performing incremental dumps is similar to performing full dumps,
although a few more options will usually be needed.
You will need to use the `-N DATE' option to tell `tar' to only
store files that have been modified since DATE. DATE should be the
date and time of the last full/incremental dump.
A standard scheme is to do a _monthly_ (full) dump once a month, a
_weekly_ dump once a week of everything since the last monthly and a
_daily_ every day of everything since the last (weekly or monthly) dump.
Here is a copy of the script used to dump the filesystems of the
machines here at the Free Software Foundation. This script is run via
`cron' late at night when people are least likely to be using the
machines. This script dumps several filesystems from several machines
at once (via NFS). The operator is responsible for ensuring that all
the machines will be up at the time the dump happens. If a machine is
not running, its files will not be dumped, and the next day's
incremental dump will _not_ store files that would have gone onto that
dump.
#!/bin/csh
# Dump thingie
set now = `date`
set then = `cat date.nfs.dump`
/u/hack/bin/tar -c -G -v\
-f /dev/rtu20\
-b 126\
-N "$then"\
-V "Dump from $then to $now"\
/alpha-bits/gp\
/gnu/hack\
/hobbes/u\
/spiff/u\
/sugar-bombs/u
echo $now > date.nfs.dump
mt -f /dev/rtu20 rew
Output from this script is stored in a file, for the operator to
read later.
This script uses the file `date.nfs.dump' to store the date/time of
the last dump.
Since this is a streaming tape drive, no attempt to verify the
archive is done. This is also why the high blocking factor (126) is
used. The tape drive must also be rewound by the `mt' command after
the dump is made.
File: tar.info, Node: incremental and listed-incremental, Next: Backup Levels, Prev: Inc Dumps, Up: Backups
The Incremental Options
=======================
_(This message will disappear, once this node revised.)_
`--incremental' (`-G') is used in conjunction with `--create' (`-c'),
`--extract' (`--get', `-x') or `--list' (`-t') when backing up and
restoring file systems. An archive cannot be extracted or listed with
the `--incremental' (`-G') option specified unless it was created with
the option specified. This option should only be used by a script, not
by the user, and is usually disregarded in favor of
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE'), which is
described below.
`--incremental' (`-G') in conjunction with `--create' (`-c') causes
`tar' to write, at the beginning of the archive, an entry for each of
the directories that will be archived. The entry for a directory
includes a list of all the files in the directory at the time the
archive was created and a flag for each file indicating whether or not
the file is going to be put in the archive.
Note that this option causes `tar' to create a non-standard archive
that may not be readable by non-GNU versions of the `tar' program.
`--incremental' (`-G') in conjunction with `--extract' (`--get',
`-x') causes `tar' to read the lists of directory contents previously
stored in the archive, _delete_ files in the file system that did not
exist in their directories when the archive was created, and then
extract the files in the archive.
This behavior is convenient when restoring a damaged file system from
a succession of incremental backups: it restores the entire state of
the file system to that which obtained when the backup was made. If
`--incremental' (`-G') isn't specified, the file system will probably
fill up with files that shouldn't exist any more.
`--incremental' (`-G') in conjunction with `--list' (`-t'), causes
`tar' to print, for each directory in the archive, the list of files in
that directory at the time the archive was created. This information
is put out in a format that is not easy for humans to read, but which
is unambiguous for a program: each file name is preceded by either a
`Y' if the file is present in the archive, an `N' if the file is not
included in the archive, or a `D' if the file is a directory (and is
included in the archive). Each file name is terminated by a null
character. The last file is followed by an additional null and a
newline to indicate the end of the data.
`--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') acts like
`--incremental' (`-G'), but when used in conjunction with `--create'
(`-c') will also cause `tar' to use the file SNAPSHOT-FILE, which
contains information about the state of the file system at the time of
the last backup, to decide which files to include in the archive being
created. That file will then be updated by `tar'. If the file FILE
does not exist when this option is specified, `tar' will create it, and
include all appropriate files in the archive.
The file FILE, which is archive independent, contains the date it
was last modified and a list of devices, inode numbers and directory
names. `tar' will archive files with newer mod dates or inode change
times, and directories with an unchanged inode number and device but a
changed directory name. The file is updated after the files to be
archived are determined, but before the new archive is actually created.
Despite it should be obvious that a device has a non-volatile value,
NFS devices have non-dependable values when an automounter gets in the
picture. This led to a great deal of spurious redumping in incremental
dumps, so it is somewhat useless to compare two NFS devices numbers
over time. So `tar' now considers all NFS devices as being equal when
it comes to comparing directories; this is fairly gross, but there does
not seem to be a better way to go.
File: tar.info, Node: Backup Levels, Next: Backup Parameters, Prev: incremental and listed-incremental, Up: Backups
Levels of Backups
=================
_(This message will disappear, once this node revised.)_
An archive containing all the files in the file system is called a
"full backup" or "full dump". You could insure your data by creating a
full dump every day. This strategy, however, would waste a substantial
amount of archive media and user time, as unchanged files are daily
re-archived.
It is more efficient to do a full dump only occasionally. To back up
files between full dumps, you can a incremental dump. A "level one"
dump archives all the files that have changed since the last full dump.
A typical dump strategy would be to perform a full dump once a week,
and a level one dump once a day. This means some versions of files
will in fact be archived more than once, but this dump strategy makes
it possible to restore a file system to within one day of accuracy by
only extracting two archives--the last weekly (full) dump and the last
daily (level one) dump. The only information lost would be in files
changed or created since the last daily backup. (Doing dumps more than
once a day is usually not worth the trouble).
GNU `tar' comes with scripts you can use to do full and level-one
dumps. Using scripts (shell programs) to perform backups and
restoration is a convenient and reliable alternative to typing out file
name lists and `tar' commands by hand.
Before you use these scripts, you need to edit the file
`backup-specs', which specifies parameters used by the backup scripts
and by the restore script. . . Once the backup parameters are set,
you can perform backups or restoration by running the appropriate
script.
The name of the restore script is `restore'. . The names of the
level one and full backup scripts are, respectively, `level-1' and
`level-0'. The `level-0' script also exists under the name `weekly',
and the `level-1' under the name `daily'--these additional names can be
changed according to your backup schedule. , for more information on
running the restoration script. , for more information on running the
backup scripts.
_Please Note:_ The backup scripts and the restoration scripts are
designed to be used together. While it is possible to restore files by
hand from an archive which was created using a backup script, and to
create an archive by hand which could then be extracted using the
restore script, it is easier to use the scripts. . *Note Inc Dumps::,
and *Note Inc Dumps::, before making such an attempt.
File: tar.info, Node: Backup Parameters, Next: Scripted Backups, Prev: Backup Levels, Up: Backups
Setting Parameters for Backups and Restoration
==============================================
_(This message will disappear, once this node revised.)_
The file `backup-specs' specifies backup parameters for the backup
and restoration scripts provided with `tar'. You must edit
`backup-specs' to fit your system configuration and schedule before
using these scripts.
, for an explanation of this syntax.
`ADMINISTRATOR'
The user name of the backup administrator.
`BACKUP_HOUR'
The hour at which the backups are done. This can be a number from
0 to 23, or the string `now'.
`TAPE_FILE'
The device `tar' writes the archive to. This device should be
attached to the host on which the dump scripts are run.
`TAPE_STATUS'
The command to use to obtain the status of the archive device,
including error count. On some tape drives there may not be such a
command; in that case, simply use `TAPE_STATUS=false'.
`BLOCKING'
The blocking factor `tar' will use when writing the dump archive.
*Note Blocking Factor::.
`BACKUP_DIRS'
A list of file systems to be dumped. You can include any directory
name in the list--subdirectories on that file system will be
included, regardless of how they may look to other networked
machines. Subdirectories on other file systems will be ignored.
The host name specifies which host to run `tar' on, and should
normally be the host that actually contains the file system.
However, the host machine must have GNU `tar' installed, and must
be able to access the directory containing the backup scripts and
their support files using the same file name that is used on the
machine where the scripts are run (ie. what `pwd' will print when
in that directory on that machine). If the host that contains the
file system does not have this capability, you can specify another
host as long as it can access the file system through NFS.
`BACKUP_FILES'
A list of individual files to be dumped. These should be
accessible from the machine on which the backup script is run.
* Menu:
* backup-specs example:: An Example Text of `Backup-specs'
* Script Syntax:: Syntax for `Backup-specs'
File: tar.info, Node: backup-specs example, Next: Script Syntax, Prev: Backup Parameters, Up: Backup Parameters
An Example Text of `Backup-specs'
---------------------------------
_(This message will disappear, once this node revised.)_
The following is the text of `backup-specs' as it appears at FSF:
# site-specific parameters for file system backup.
ADMINISTRATOR=friedman
BACKUP_HOUR=1
TAPE_FILE=/dev/nrsmt0
TAPE_STATUS="mts -t $TAPE_FILE"
BLOCKING=124
BACKUP_DIRS="
albert:/fs/fsf
apple-gunkies:/gd
albert:/fs/gd2
albert:/fs/gp
geech:/usr/jla
churchy:/usr/roland
albert:/
albert:/usr
apple-gunkies:/
apple-gunkies:/usr
gnu:/hack
gnu:/u
apple-gunkies:/com/mailer/gnu
apple-gunkies:/com/archive/gnu"
BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
File: tar.info, Node: Script Syntax, Prev: backup-specs example, Up: Backup Parameters
Syntax for `Backup-specs'
-------------------------
_(This message will disappear, once this node revised.)_
`backup-specs' is in shell script syntax. The following conventions
should be considered when editing the script:
A quoted string is considered to be contiguous, even if it is on more
than one line. Therefore, you cannot include commented-out lines
within a multi-line quoted string. BACKUP_FILES and BACKUP_DIRS are
the two most likely parameters to be multi-line.
A quoted string typically cannot contain wildcards. In
`backup-specs', however, the parameters BACKUP_DIRS and BACKUP_FILES
can contain wildcards.
File: tar.info, Node: Scripted Backups, Next: Scripted Restoration, Prev: Backup Parameters, Up: Backups
Using the Backup Scripts
========================
_(This message will disappear, once this node revised.)_
The syntax for running a backup script is:
`script-name' [TIME-TO-BE-RUN]
where TIME-TO-BE-RUN can be a specific system time, or can be `now'.
If you do not specify a time, the script runs at the time specified in
`backup-specs' ().
You should start a script with a tape or disk mounted. Once you
start a script, it prompts you for new tapes or disks as it needs them.
Media volumes don't have to correspond to archive files--a
multi-volume archive can be started in the middle of a tape that
already contains the end of another multi-volume archive. The
`restore' script prompts for media by its archive volume, so to avoid
an error message you should keep track of which tape (or disk) contains
which volume of the archive. . .
The backup scripts write two files on the file system. The first is
a record file in `/etc/tar-backup/', which is used by the scripts to
store and retrieve information about which files were dumped. This
file is not meant to be read by humans, and should not be deleted by
them. , for a more detailed explanation of this file.
The second file is a log file containing the names of the file
systems and files dumped, what time the backup was made, and any error
messages that were generated, as well as how much space was left in the
media volume after the last volume of the archive was written. You
should check this log file after every backup. The file name is
`log-MMM-DDD-YYYY-level-1' or `log-MMM-DDD-YYYY-full'.
The script also prints the name of each system being dumped to the
standard output.
File: tar.info, Node: Scripted Restoration, Prev: Scripted Backups, Up: Backups
Using the Restore Script
========================
_(This message will disappear, once this node revised.)_
*Warning:* The GNU `tar' distribution does _not_ provide any such
`restore' script yet. This section is only listed here for
documentation maintenance purposes. In any case, all contents is
subject to change as things develop.
To restore files that were archived using a scripted backup, use the
`restore' script. The syntax for the script is:
where ***** are the file systems to restore from, and ***** is a
regular expression which specifies which files to restore. If you
specify -all, the script restores all the files in the file system.
You should start the restore script with the media containing the
first volume of the archive mounted. The script will prompt for other
volumes as they are needed. If the archive is on tape, you don't need
to rewind the tape to to its beginning--if the tape head is positioned
past the beginning of the archive, the script will rewind the tape as
needed. , for a discussion of tape positioning.
If you specify `--all' as the FILES argument, the `restore' script
extracts all the files in the archived file system into the active file
system.
*Warning:* The script will delete files from the active file
system if they were not in the file system when the archive was
made.
*Note Inc Dumps::, and *Note Inc Dumps::, for an explanation of how
the script makes that determination.
File: tar.info, Node: Choosing, Next: Date input formats, Prev: Backups, Up: Top
Choosing Files and Names for `tar'
**********************************
_(This message will disappear, once this node revised.)_
Certain options to `tar' enable you to specify a name for your
archive. Other options let you decide which files to include or exclude
from the archive, based on when or whether files were modified, whether
the file names do or don't match specified patterns, or whether files
are in specified directories.
* Menu:
* file:: Choosing the Archive's Name
* Selecting Archive Members::
* files:: Reading Names from a File
* exclude:: Excluding Some Files
* Wildcards::
* after:: Operating Only on New Files
* recurse:: Descending into Directories
* one:: Crossing Filesystem Boundaries
File: tar.info, Node: file, Next: Selecting Archive Members, Prev: Choosing, Up: Choosing
Choosing and Naming Archive Files
=================================
_(This message will disappear, once this node revised.)_
By default, `tar' uses an archive file name that was compiled when
it was built on the system; usually this name refers to some physical
tape drive on the machine. However, the person who installed `tar' on
the system may not set the default to a meaningful value as far as most
users are concerned. As a result, you will usually want to tell `tar'
where to find (or create) the archive. The `--file=ARCHIVE-NAME' (`-f
ARCHIVE-NAME') option allows you to either specify or name a file to
use as the archive instead of the default archive file location.
`--file=ARCHIVE-NAME'
`-f ARCHIVE-NAME'
Name the archive to create or operate on. Use in conjunction with
any operation.
For example, in this `tar' command,
$ tar -cvf collection.tar blues folk jazz
`collection.tar' is the name of the archive. It must directly follow
the `-f' option, since whatever directly follows `-f' _will_ end up
naming the archive. If you neglect to specify an archive name, you may
end up overwriting a file in the working directory with the archive you
create since `tar' will use this file's name for the archive name.
An archive can be saved as a file in the file system, sent through a
pipe or over a network, or written to an I/O device such as a tape,
floppy disk, or CD write drive.
If you do not name the archive, `tar' uses the value of the
environment variable `TAPE' as the file name for the archive. If that
is not available, `tar' uses a default, compiled-in archive name,
usually that for tape unit zero (ie. `/dev/tu00'). `tar' always needs
an archive name.
If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from
standard input (when listing or extracting files), or writes it to
standard output (when creating an archive). If you use `-' as an
ARCHIVE-NAME when modifying an archive, `tar' reads the original
archive from its standard input and writes the entire new archive to
its standard output.
$ cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)
To specify an archive file on a device attached to a remote machine,
use the following:
--file=HOSTNAME:/DEV/FILE NAME
`tar' will complete the remote connection, if possible, and prompt you
for a username and password. If you use `--file=@HOSTNAME:/DEV/FILE
NAME', `tar' will complete the remote connection, if possible, using
your username as the username on the remote machine.
If the archive file name includes a colon (`:'), then it is assumed
to be a file on another machine. If the archive file is
`USER@HOST:FILE', then FILE is used on the host HOST. The remote host
is accessed using the `rsh' program, with a username of USER. If the
username is omitted (along with the `@' sign), then your user name will
be used. (This is the normal `rsh' behavior.) It is necessary for the
remote machine, in addition to permitting your `rsh' access, to have
the `/usr/ucb/rmt' program installed. If you need to use a file whose
name includes a colon, then the remote tape drive behavior can be
inhibited by using the `--force-local' option.
When the archive is being created to `/dev/null', GNU `tar' tries to
minimize input and output operations. The Amanda backup system, when
used with GNU `tar', has an initial sizing pass which uses this feature.
File: tar.info, Node: Selecting Archive Members, Next: files, Prev: file, Up: Choosing
Selecting Archive Members
=========================
"File Name arguments" specify which files in the file system `tar'
operates on, when creating or adding to an archive, or which archive
members `tar' operates on, when reading or deleting from an archive.
*Note Operations::.
To specify file names, you can include them as the last arguments on
the command line, as follows:
tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
If you specify a directory name as a file name argument, all the
files in that directory are operated on by `tar'.
If you do not specify files when `tar' is invoked with `--create'
(`-c'), `tar' operates on all the non-directory files in the working
directory. If you specify either `--list' (`-t') or `--extract'
(`--get', `-x'), `tar' operates on all the archive members in the
archive. If you specify any operation other than one of these three,
`tar' does nothing.
By default, `tar' takes file names from the command line. However,
there are other ways to specify file or member names, or to modify the
manner in which `tar' selects the files or members upon which to
operate; . In general, these methods work both for specifying the
names of files and archive members.
File: tar.info, Node: files, Next: exclude, Prev: Selecting Archive Members, Up: Choosing
Reading Names from a File
=========================
_(This message will disappear, once this node revised.)_
Instead of giving the names of files or archive members on the
command line, you can put the names into a file, and then use the
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
Give the name of the file which contains the list of files to include
as the argument to `--files-from'. In the list, the file names should
be separated by newlines. You will frequently use this option when you
have generated the list of files to archive with the `find' utility.
`--files-from=FILE NAME'
`-T FILE NAME'
Get names to extract or create from file FILE NAME.
If you give a single dash as a file name for `--files-from', (i.e.,
you specify either `--files-from=-' or `-T -'), then the file names are
read from standard input.
Unless you are running `tar' with `--create', you can not use both
`--files-from=-' and `--file=-' (`-f -') in the same command.
The following example shows how to use `find' to generate a list of
files smaller than 400K in length and put that list into a file called
`small-files'. You can then use the `-T' option to `tar' to specify
the files from that file, `small-files', to create the archive
`little.tgz'. (The `-z' option to `tar' compresses the archive with
`gzip'; *note gzip::. for more information.)
$ find . -size -400 -print > small-files
$ tar -c -v -z -T small-files -f little.tgz
* Menu:
* nul::
File: tar.info, Node: nul, Prev: files, Up: files
`NUL' Terminated File Names
---------------------------
The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a
newline, so files whose names contain newlines can be archived using
`--files-from'.
`--null'
Only consider `NUL' terminated file names, instead of files that
terminate in a newline.
The `--null' option is just like the one in GNU `xargs' and `cpio',
and is useful with the `-print0' predicate of GNU `find'. In `tar',
`--null' also causes `--directory=DIRECTORY' (`-C DIRECTORY') options
to be treated as file names to archive, in case there are any files out
there called `-C'.
This example shows how to use `find' to generate a list of files
larger than 800K in length and put that list into a file called
`long-files'. The `-print0' option to `find' just just like `-print',
except that it separates files with a `NUL' rather than with a newline.
You can then run `tar' with both the `--null' and `-T' options to
specify that `tar' get the files from that file, `long-files', to
create the archive `big.tgz'. The `--null' option to `tar' will cause
`tar' to recognize the `NUL' separator between files.
$ find . -size +800 -print0 > long-files
$ tar -c -v --null --files-from=long-files --file=big.tar
File: tar.info, Node: exclude, Next: Wildcards, Prev: files, Up: Choosing
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=PATTERN' or `--exclude-from=FILE-OF-PATTERNS' (`-X
FILE-OF-PATTERNS') options.
`--exclude=PATTERN'
Causes `tar' to ignore files that match the PATTERN.
The `--exclude=PATTERN' option will prevent any file or member which
matches the shell wildcards (PATTERN) from being operated on (PATTERN
can be a single file name or a more complex expression). For example,
if you want to create an archive with all the contents of `/tmp' except
the file `/tmp/foo', you can use the command `tar --create
--file=arch.tar --exclude=foo'. You may give multiple `--exclude'
options.
`--exclude-from=FILE'
`-X FILE'
Causes `tar' to ignore files that match the patterns listed in
FILE.
Use the `--exclude-from=FILE-OF-PATTERNS' option to read a list of
shell wildcards, one per line, from FILE; `tar' will ignore files
matching those regular expressions. Thus if `tar' is called as
`tar -c -X foo .' and the file `foo' contains a single line `*.o', no
files whose names end in `.o' will be added to the archive.
* Menu:
* problems with exclude::
File: tar.info, Node: problems with exclude, Prev: exclude, Up: exclude
Problems with Using the `exclude' Options
-----------------------------------------
Some users find `exclude' options confusing. Here are some common
pitfalls:
* The main operating mode of `tar' will always act on file names
listed on the command line, no matter whether or not there is an
exclusion which would otherwise affect them. In the example
above, if you create an archive and exclude files that end with
`*.o', but explicitly name the file `catc.o' after all the options
have been listed, `catc.o' _will_ be included in the archive.
* You can sometimes confuse the meanings of `--exclude=PATTERN' and
`--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS'). Be
careful: use `--exclude=PATTERN' when files to be excluded are
given as a pattern on the command line. Use
`--exclude-from=FILE-OF-PATTERNS' to introduce the name of a file
which contains a list of patterns, one per line; each of these
patterns can exclude zero, one, or many files.
* When you use `--exclude=PATTERN', be sure to quote the PATTERN
parameter, so GNU `tar' sees wildcard characters like `*'. If you
do not do this, the shell might expand the `*' itself using files
at hand, so `tar' might receive a list of files instead of one
pattern, or none at all, making the command somewhat illegal.
This might not correspond to what you want.
For example, write:
$ tar -c -f ARCHIVE.TAR -X '*/tmp/*' DIRECTORY
rather than:
$ tar -c -f ARCHIVE.TAR -X */tmp/* DIRECTORY
* You must use use shell syntax, or globbing, rather than `regexp'
syntax, when using exclude options in `tar'. If you try to use
`regexp' syntax to describe files to be excluded, your command
might fail.
* In earlier versions of `tar', what is now the
`--exclude-from=FILE-OF-PATTERNS' option was called
`--exclude-PATTERN' instead. Now, `--exclude=PATTERN' applies to
patterns listed on the command line and
`--exclude-from=FILE-OF-PATTERNS' applies to patterns listed in a
file.
File: tar.info, Node: Wildcards, Next: after, Prev: exclude, Up: Choosing
Wildcards Patterns and Matching
===============================
"Globbing" is the operation by which "wildcard" characters, `*' or
`?' for example, are replaced and expanded into all existing files
matching the given pattern. However, `tar' often uses wildcard
patterns for matching (or globbing) archive members instead of actual
files in the filesystem. Wildcard patterns are also used for verifying
volume labels of `tar' archives. This section has the purpose of
explaining wildcard syntax for `tar'.
A PATTERN should be written according to shell syntax, using wildcard
characters to effect globbing. Most characters in the pattern stand
for themselves in the matched string, and case is significant: `a' will
match only `a', and not `A'. The character `?' in the pattern matches
any single character in the matched string. The character `*' in the
pattern matches zero, one, or more single characters in the matched
string. The character `\' says to take the following character of the
pattern _literally_; it is useful when one needs to match the `?', `*',
`[' or `\' characters, themselves.
The character `[', up to the matching `]', introduces a character
class. A "character class" is a list of acceptable characters for the
next single character of the matched string. For example, `[abcde]'
would match any of the first five letters of the alphabet. Note that
within a character class, all of the "special characters" listed above
other than `\' lose their special meaning; for example, `[-\\[*?]]'
would match any of the characters, `-', `\', `[', `*', `?', or `]'.
(Due to parsing constraints, the characters `-' and `]' must either
come _first_ or _last_ in a character class.)
If the first character of the class after the opening `[' is `!' or
`^', then the meaning of the class is reversed. Rather than listing
character to match, it lists those characters which are _forbidden_ as
the next single character of the matched string.
Other characters of the class stand for themselves. The special
construction `[A-E]', using an hyphen between two letters, is meant to
represent all characters between A and E, inclusive.
Periods (`.') or forward slashes (`/') are not considered special
for wildcard matches. However, if a pattern completely matches a
directory prefix of a matched string, then it matches the full matched
string: excluding a directory also excludes all the files beneath it.
There are some discussions floating in the air and asking for
modifications in the way GNU `tar' accomplishes wildcard matches. We
perceive any change of semantics in this area as a delicate thing to
impose on GNU `tar' users. On the other hand, the GNU project should be
progressive enough to correct any ill design: compatibility at all price
is not always a good attitude. In conclusion, it is _possible_ that
slight amendments be later brought to the previous description. Your
opinions on the matter are welcome.
File: tar.info, Node: after, Next: recurse, Prev: Wildcards, Up: Choosing
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 modification or inode-changed times
are newer than the DATE given. If you use this option when creating or
appending to an archive, the archive will only include new files. If
you use `--after-date' when extracting an archive, `tar' will only
extract files newer than the DATE you specify.
If you only want `tar' to make the date comparison based on
modification of the actual contents of the file (rather than inode
changes), then use the `--newer-mtime=DATE' option.
You may use these options with any operation. Note that these
options differ from the `--update' (`-u') operation in that they allow
you to specify a particular date against which `tar' can compare when
deciding whether or not to archive the files.
`--after-date=DATE'
`--newer=DATE'
`-N DATE'
Only store files newer than DATE.
Acts on files only if their modification or inode-changed times are
later than DATE. Use in conjunction with any operation.
`--newer-mtime=DATE'
Acts like `--after-date=DATE' (`--newer=DATE', `-N DATE'), but
only looks at modification times.
These options limit `tar' to only operating on files which have been
modified after the date specified. A file is considered to have
changed if the contents have been modified, or if the owner,
permissions, and so forth, have been changed. (For more information on
how to specify a date, see *Note Date input formats::; remember that the
entire date argument must be quoted if it contains any spaces.)
Gurus would say that `--after-date=DATE' (`--newer=DATE', `-N DATE')
tests both the `mtime' (time the contents of the file were last
modified) and `ctime' (time the file's status was last changed: owner,
permissions, etc) fields, while `--newer-mtime=DATE' tests only `mtime'
field.
To be precise, `--after-date=DATE' (`--newer=DATE', `-N DATE')
checks _both_ `mtime' and `ctime' and processes the file if either one
is more recent than DATE, while `--newer-mtime=DATE' only checks
`mtime' and disregards `ctime'. Neither uses `atime' (the last time the
contents of the file were looked at).
Date specifiers can have embedded spaces. Because of this, you may
need to quote date arguments to keep the shell from parsing them as
separate arguments.
*Please Note:* `--after-date=DATE' (`--newer=DATE', `-N DATE') and
`--newer-mtime=DATE' should not be used for incremental backups.
Some files (such as those in renamed directories) are not selected
properly by these options. *Note incremental and
listed-incremental::.
To select files newer than the modification time of a file that
already exists, you can use the `--reference' (`-r') option of GNU
`date', available in GNU shell utilities 1.13 or later. It returns the
timestamp of that already existing file; this timestamp expands to
become the referent date which `--newer' uses to determine which files
to archive. For example, you could say,
$ tar -cf ARCHIVE.TAR --newer="`date -r FILE`" /home
which tells .
File: tar.info, Node: recurse, Next: one, Prev: after, Up: Choosing
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=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option) for the
various files they contain. However, you may not always want `tar' to
act this way.
The `--no-recursion' option inhibits `tar''s recursive descent into
specified directories. If you specify `--no-recursion', you can use
the `find' utility for hunting through levels of directories to
construct a list of file names which you could then pass to `tar'.
`find' allows you to be more selective when choosing which files to
archive; see *Note files:: for more information on using `find' with
`tar', or look.
`--no-recursion'
Prevents `tar' from recursively descending directories.
When you use `--no-recursion', GNU `tar' grabs directory entries
themselves, but does not descend on them recursively. Many people use
`find' for locating files they want to back up, and since `tar'
_usually_ recursively descends on directories, they have to use the
`! -d' option to `find' as they usually do not want all the files in a
directory. They then use the {No Value For "op-file-from"} option to
archive the files located via `find'.
The problem when restoring files archived in this manner is that the
directories themselves are not in the archive; so the
`--same-permissions' (`--preserve-permissions', `-p') option does not
affect them--while users might really like it to. Specifying
`--no-recursion' is a way to tell `tar' to grab only the directory
entries given to it, adding no new files on its own.
File: tar.info, Node: one, Prev: recurse, Up: Choosing
Crossing Filesystem 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' (`-l'). This option only affects files that are
archived because they are in a directory that is being archived; `tar'
will still archive files explicitly named on the command line or
through `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), regardless
of where they reside.
`--one-file-system'
`-l'
Prevents `tar' from crossing file system boundaries when
archiving. Use in conjunction with any write operation.
The `--one-file-system' option causes `tar' to modify its normal
behavior in archiving the contents of directories. If a file in a
directory is not on the same filesystem as the directory itself, then
`tar' will not archive that file. If the file is a directory itself,
`tar' will not archive anything beneath it; in other words, `tar' will
not cross mount points.
It is reported that using this option, the mount point is is
archived, but nothing under it.
This option is useful for making full or incremental archival
backups of a file system. If this option is used in conjunction with
`--verbose' (`-v'), files that are excluded are mentioned by name on the
standard error.
* Menu:
* directory:: Changing Directory
* absolute:: Absolute File Names
File: tar.info, Node: directory, Next: absolute, Prev: one, Up: one
Changing the Working Directory
------------------------------
_(This message will disappear, once this node revised.)_
To change the working directory in the middle of a list of file
names, either on the command line or in a file specified using
`--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), use
`--directory=DIRECTORY' (`-C DIRECTORY'). This will change the working
directory to the directory DIRECTORY after that point in the list.
`--directory=DIRECTORY'
`-C DIRECTORY'
Changes the working directory in the middle of a command line.
For example,
$ tar -c -f jams.tar grape prune -C food cherry
will place the files `grape' and `prune' from the current directory
into the archive `jams.tar', followed by the file `cherry' from the
directory `food'. This option is especially useful when you have
several widely separated files that you want to store in the same
archive.
Note that the file `cherry' is recorded in the archive under the
precise name `cherry', _not_ `food/cherry'. Thus, the archive will
contain three files that all appear to have come from the same
directory; if the archive is extracted with plain `tar --extract', all
three files will be written in the current directory.
Contrast this with the command,
$ tar -c -f jams.tar grape prune -C food red/cherry
which records the third file in the archive under the name `red/cherry'
so that, if the archive is extracted using `tar --extract', the third
file will be written in a subdirectory named `orange-colored'.
You can use the `--directory' option to make the archive independent
of the original name of the directory holding the files. The following
command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a'
into the archive `foo.tar':
$ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
However, the names of the archive members will be exactly what they were
on the command line: `passwd', `hosts', and `libc.a'. They will not
appear to be related by file name to the original directories where
those files were located.
Note that `--directory' options are interpreted consecutively. If
`--directory' specifies a relative file name, it is interpreted
relative to the then current directory, which might not be the same as
the original current working directory of `tar', due to a previous
`--directory' option.
When using `--files-from' (*note files::.), you can put `-C' options
in the file list. Unfortunately, you cannot put `--directory' options
in the file list. (This interpretation can be disabled by using the
`--null' option.)
File: tar.info, Node: absolute, Prev: directory, Up: one
Absolute File Names
-------------------
_(This message will disappear, once this node revised.)_
`-P'
`--absolute-names'
Do not strip leading slashes from file names.
By default, GNU `tar' drops a leading `/' on input or output. This
option turns off this behavior; it is equivalent to changing to the
root directory before running `tar' (except it also turns off the usual
warning message).
When `tar' extracts archive members from an archive, it strips any
leading slashes (`/') from the member name. This causes absolute
member names in the archive to be treated as relative file names. This
allows you to have such members extracted wherever you want, instead of
being restricted to extracting the member in the exact directory named
in the archive. For example, if the archive member has the name
`/etc/passwd', `tar' will extract it as if the name were really
`etc/passwd'.
Other `tar' programs do not do this. As a result, if you create an
archive whose member names start with a slash, they will be difficult
for other people with a non-GNU `tar' program to use. Therefore, GNU
`tar' also strips leading slashes from member names when putting
members into the archive. For example, if you ask `tar' to add the
file `/bin/ls' to an archive, it will do so, but the member name will
be `bin/ls'.
If you use the `--absolute-names' (`-P') option, `tar' will do
neither of these transformations.
To archive or extract files relative to the root directory, specify
the `--absolute-names' (`-P') option.
Normally, `tar' acts on files relative to the working
directory--ignoring superior directory names when archiving, and
ignoring leading slashes when extracting.
When you specify `--absolute-names' (`-P'), `tar' stores file names
including all superior directory names, and preserves leading slashes.
If you only invoked `tar' from the root directory you would never need
the `--absolute-names' (`-P') option, but using this option may be more
convenient than switching to root.
`--absolute-names'
Preserves full file names (inclusing superior dirctory names) when
archiving files. Preserves leading slash when extracting files.
`tar' prints out a message about removing the `/' from file names.
This message appears once per GNU `tar' invocation. It represents
something which ought to be told; ignoring what it means can cause very
serious surprises, later.
Some people, nevertheless, do not want to see this message. Wanting
to play really dangerously, one may of course redirect `tar' standard
error to the sink. For example, under `sh':
$ tar -c -f archive.tar /home 2> /dev/null
Another solution, both nicer and simpler, would be to change to the `/'
directory first, and then avoid absolute notation. For example:
$ (cd / && tar -c -f archive.tar home)
$ tar -c -f archive.tar -C / home