tar Operations@UNREVISED
This chapter describes the basic operations supported by the tar
program. A given invocation of tar will do exactly one of these
operations.
An archive member in normally extracted into a file with the same name
as the archive member. However, you can use the `--to-stdout' (`-O') to
cause tar to write extracted archive members to standard output.
If you extract multiple members, they appear on standard output
concatenated, in the order they are found in the archive.
The `--create' (`-c') operation writes a new archive, and the
`--extract' (`-x') operation reads files from an archive and writes them
into the file system. You can use other tar operations to
write new information into an existing archive (adding files to it,
adding another archive to it, or deleting files from it), and you can
read a list of the files in an archive without extracting it using the
`--list' (`-t') operation.
The primary argument to tar is the operation, which specifies
what tar does. tar can be used to:
See section Basic tar Operations, for more information about these operations.
Option arguments to tar change details of the operation, such as
archive format, archive name, or level of user interaction. You can
specify more than one option. All options are optional.
File Name arguments specify which files (including directory files) to archive, extract, delete or otherwise operate on.
If you don't use any file name arguments, `--append' (`-r'), `--update' (`-u') and
`--delete' will do nothing. The other operations of tar will act on
defaults.
When you use a file name argument to specify a directory file, tar
acts on all the files in that directory, including sub-directories.
You must give exactly one option from the following list to tar. This
option specifies the basic operation for tar to perform.
The remaining options to tar change details of the operation,
such as archive format, archive name, or level of user interaction.
You can specify more than one option.
The remaining arguments are interpreted either as file names or as
member names, depending on the basic operation tar is
performing. For `--append' (`-r') and `--create' (`-c') these arguments
specify the names of files (which must already exist) to place in the
archive. For the remaining operation types, the additional arguments
specify archive members to compare, delete, extract, list, or update.
When naming archive members, you must give the exact name of the member
in the archive, as it is printed by `--list' (`-t'). When naming
files, the normal file name rules apply.
If you give the name of a directory as either a file name or a member
name, then tar acts recursively on all the files and directories
beneath that directory. For example, the name `/' identifies all
the files in the filesystem to tar.
The operation argument to tar specifies which action you want to
take.
tar program to the standard
error.
If you don't use any additional arguments, `--append' (`-r'),
`--concatenate' (`-A'), and `--delete' will do nothing. Naturally,
`--create' (`-c') will make an empty archive if given no files to
add (however, see below). The other operations of tar
(`--list' (`-t'), `--extract' (`-x'), `--compare' (`-d'), and `--update' (`-u'))
will act on the entire contents of the archive.
Creating an empty archive has some kind of elegance. One can
initialize an empty archive and later use `--append' (`-r') for adding
all members. Some applications would not welcome making an exception
in the way of adding the first archive member. On the other hand,
many people reported that it is dangerously too easy for tar
to destroy a magnetic tape with an empty archive(1).
The two most common errors are:
create instead of extract, when the
intent was to extract the full contents of an archive. This error
is likely: keys c and x are right next ot each other on
the QWERTY keyboard. Instead of being unpacked, the archive then
gets wholly destroyed. When users speak about exploding an
archive, they usually mean something else :-).
file, when the intent was to create
an archive with a single file in it. This error is likely because a
tired user can easily add the f key to the cluster of option
letters, by the mere force of habit, without realizing the full
consequence of doing so. The usual consequence is that the single
file, which was meant to be saved, is rather destroyed.
So, recognizing the likelihood and the catastrophical nature of these
errors, GNU tar now takes some distance from elegance, and
cowardly refuses to create an archive when `--create' (`-c') option is
given, there are no arguments besides options, and `--files-from=file-of-names' (`-T file-of-names')
option is not used. To get around the cautiousness of GNU
tar and nevertheless create an archive with nothing in it,
one may still use, as the value for the `--files-from=file-of-names' (`-T file-of-names') option,
a file with no names in it, as shown in the following commands:
tar --create --file=empty-archive.tar --files-from=/dev/null tar cfT empty-archive.tar /dev/null
The program tar can create an archive, extract files from an
archive, modify an archive, or list an archive's contents. Each time
you run tar, you must give a command to specify which one
of these things you want to do.
The command must always be in the first argument to tar.
This argument can also contain options (see section Invoking GNU tar).
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.
In addition, a set of long-named options are provided which can be used instead of or intermixed with the single-letter flags. The long-named options are meant to be easy to remember and logical, while the single letter flags may not always be. Long-named options begin with `--'.
Arguments after the first are either options, if they start with `-' or `--', or files to operate on.
The file names that you give as arguments are the files that tar
will act on--for example, they are the files to put in the archive, or
the files to extract from it. If you don't give any file name
arguments, the default depends on which command you used. Some commands
use all relevant files; some commands have no default and will report an
error if you don't specify files.
If a file name argument actually names a directory, then that directory and all files and subdirectories (recursively) in it are used.
Here is a list of the tar commands:
-c
--create
tar to create a new archive that contains
the file(s) specified on the command line. If you don't specify
files, all the files in the current directory are used.
If the archive file already exists, it is overwritten; the old contents
are lost.
-x
--extract
--get
tar to extract the specified files from
the archive. If no file names are given, all the files in the archive
will be extracted.
-t
--list
tar to display a list of the files in
the archive. If you specify file names, only the files that you
specify will be mentioned (but each of them is mentioned only if it
appears in the archive).
-d
--diff
--compare
tar to compare the archive with the files
in the file system. It will report differences in file size, mode,
owner, and contents. If a file exists in the archive, but not in
the file system, tar will report this.
If you specify file names, those files are compared with the tape and
they must all exist in the archive. If you don't specify files, all
the files in the archive are compared.
-r
--append
tar to add the specified file(s) to the end
of the archive. This assumes that the archive file already exists
and is in the proper format (which probably means it was created
previously with the tar program). If the archive is not in a
format that tar understands, the results will be unpredictable.
You must specify the files to be used; there is no default.
-u
--update
tar to add the specified files to the end
of the archive, like `--append' (`-r'), but only when a file doesn't
already exist in the archive or is newer than the version in the
archive (the last-modification time is compared). Adding files to
the end of an archive can be very slow.
You must specify the files to be used; there is no default.
-A
--catenate
--concatenate
tar
works on. (The other files are not changed).
You might be tempted to use cat for this, but it won't ordinarily
work. A tar archive contains data which indicates the end of the
archive, so appended material is ignored. This command works because it
removes the end-of-archive markers from the middle of the result.
--delete
tar to delete the specified files from the
archive. This command is extremely slow. Warning: Use of this command
on archives stored on magnetic tape may result in a scrambled archive.
There is no safe way (except for completely re-writing the archive)
to delete files from a magnetic tape.
The program tar can create an archive, extract files from an
archive, modify an archive, or list an archive's contents. Each time
you run tar, you must give a command to specify which one
of these things you want to do.
The command must always be in the first argument to tar.
This argument can also contain options (see section Invoking GNU tar).
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.
In addition, a set of long-named options are provided which can be used instead of or intermixed with the single-letter flags. The long-named options are meant to be easy to remember and logical, while the single letter flags may not always be. Long-named options begin with `--'.
Arguments after the first are either options, if they start with `-' or `--', or files to operate on.
The file names that you give as arguments are the files that tar
will act on--for example, they are the files to put in the archive, or
the files to extract from it. If you don't give any file name
arguments, the default depends on which command you used. Some commands
use all relevant files; some commands have no default and will report an
error if you don't specify files.
If a file name argument actually names a directory, then that directory and all files and subdirectories (recursively) in it are used.
Once an archive is created, you can add new archive members to it, add the contents of another archive, add newer versions of members already stored, or delete archive members already stored.
To find out what files are already stored in an archive, use `tar --list --file=archive-name'. See section Listing Archive Members.
@UNREVISED
The `--create' (`-c') option causes tar to create a new archive.
The files to be archived are then named on the command line. Each file
will be added to the archive with a member name exactly the same as
the name given on the command line. (When you give an absolute file
name tar actually modifies it slightly, section Absolute File Names.)
If you list no files to be archived, then an empty archive is created.
If there are two many files to conveniently list on the command line,
you can list the names in a file, and tar will read that file.
See section Reading Names from a File.
If you name a directory, then tar will archive not only the
directory, but all its contents, recursively. For example, if you name
`/', then tar will archive the entire filesystem.
Do not use the option to add files to an existing archive; it will delete the archive and write a new one. Use `--append' (`-r') instead. See section Adding to an Existing Archive.
There are various ways of causing tar to skip over some files,
and not archive them. See section Choosing Files and Names for tar.
@FIXME{operations should probably have examples, not tables.}
To create an archive, use `--create' (`-c'). To name the archive, use
`--file=archive-name' in conjunction with the `--create' (`-c')
operation (see section Changing the Archive Name). If you do not name the archive, tar
uses the value of the environment variable TAPE as the file
name for the archive, or, if that is not available, tar uses a
default archive name, usually that for tape unit zero. See section Changing the Archive Name,
for more information about specifying an archive name.
The following example creates an archive named `stooges', containing the files `larry', `moe' and `curley':
tar --create --file=stooges larry moe curley
If you specify a directory name as a file name argument, tar
will archive all the files in that directory. The following example
creates an archive named `hail/hail/fredonia', containing the
contents of the directory `marx':
tar --create --file=hail/hail/fredonia marx
If you don't specify files to put in the archive, tar archives
all the files in the working directory. The following example creates
an archive named `home' containing all the files in the working
directory:
tar --create --file=home
See section Reading Names from a File, for other ways to specify files to archive.
Note: In the example above, an archive containing all the files in the
working directory is being written to the working directory. GNU
tar stores files in the working directory in an archive which
is itself in the working directory without falling into an infinite
loop. Other versions of tar may fall into this trap.
@UNREVISED
The `--append' (`-r') option will case tar to add new
files to an existing archive. It interprets file names and member names
in exactly the same manner as `--create' (`-c'). Nothing happens if you
don't list any names.
This option never deletes members. If a new member is added under the same name as an existing member, then both will be in the archive, with the new member after the old one. For information on how this affects reading the archive, @FIXME-ref{Multiple Members with the Same Name}.
This operation cannot be performed on some tape drives, unfortunately, due to deficiencies in the formats thoes tape drives use.
To add files to an archive, use `--append' (`-r'). The archive to
be added to must already exist and be in proper archive format (which
normally means it was created previously using tar). If the
archive was created with a different record size than now specified,
tar will report an error (@FIXME-pxref{Blocking Factor}). If the
archive is not a valid tar archive, the results will be
unpredictable. You cannot add files to a compressed archive, however
you can add files to the last volume of a multi-volume archive.
@FIXME-xref{Matching Format Parameters}.
The following example adds the file `shemp' to the archive `stooges' created above:
tar --append --file=stooges shemp
You must specify the files to be added; there is no default.
`--update' (`-u') acts like `--append' (`-r'), but does not add files to the archive if there is already a file entry with that name in the archive that has the same modification time.
Both `--update' (`-u') and `--append' (`-r') work by adding to the end of the archive. When you extract a file from the archive, only the version stored last will wind up in the file system. Because `--extract' (`-x') extracts files from an archive in sequence, and overwrites files with the same name in the file system, if a file name appears more than once in an archive the last version of the file will overwrite the previous versions which have just been extracted. You should avoid storing older versions of a file later in the archive.
Note: `--update' (`-u') is not suitable for performing backups, because it doesn't change directory content entries, and because it lengthens the archive every time it is used. @FIXME-xref{to scripted backup, listed incremental, for info on backups.}
@UNREVISED
The `--update' (`-u') option updates a tar archive by comparing
the date of the specified archive members against the date of
the file with the same name. If the file has been modified more
recently than the archive member, then the archive member is deleted
(as with `--delete') and then the file is added to the archive
(as with `--append' (`-r')). On media where the `--delete' option
cannot be performed (such as magnetic tapes), the `--update' (`-u')
option similarly fails.
If no archive members are named (either on the command line or via `--files-from=file-of-names' (`-T file-of-names')), then the entire archive is processed in this manner.
@UNREVISED
The `--concatenate' (`-A') or option causes tar
to add the contents of several archives to an existing archive.
Name the archives to be catenated on the command line. (Nothing happens if you don't list any.) The members, and their member names, will be copied verbatim from those archives. If this causes multiple members to have the same name, it does not delete either; all the members with the same name coexist. For information on how this affects reading the archive, @FIXME-ref{Multiple Members with the Same Name}.
You must use this option to concatenate archives. If you just combine
them with cat, the result will not be a valid tar format
archive.
This operation cannot be performed on some tape drives, unfortunately, due to deficiencies in the formats thoes tape drives use.
To append copies of an archive or archives to the end of another archive, use `--concatenate' (`-A'). The source and target archives must already exist and have been created using compatable format parameters (@FIXME-pxref{Matching Format Parameters}).
tar will stop reading an archive if it encounters an
end-of-archive marker. The cat utility does not remove
end-of-archive markers, and is therefore unsuitable for concatenating
archives. `--concatenate' (`-A') removes the end-of-archive marker
from the target archive before each new archive is appended.
@FIXME-xref{ignore-zeros}. You must specify the source archives using
`--file=archive-name' (`-f archive-name') (see section Changing the Archive Name). If you do not specify the target archive,
tar uses the value of the environment variable TAPE,
or, if this has not been set, the default archive name.
The following example adds the contents of the archive `hail/hail/fredonia' to the archive `stooges' (both archives were created in examples above):
tar --catenate --file=stooges hail/hail/fredonia
If you need to retrieve files from an archive that was added to
using the cat utility, use the `--ignore-zeros' (`-i') option.
See section Options to Help Read Archives.
@UNREVISED
You can use the `--delete' option to remove members from an archive. Name the members on the command line to be deleted. This option will rewrite the archive; because of this, it does not work on tape drives. If you list no members to be deleted, nothing happens.
To delete archive members from an archive, use `--delete'. You must specify the file names of the members to be deleted. All archive members with the specified file names will be removed from the archive.
The following example removes the file `curley' from the archive `stooges':
tar --delete --file=stooges curley
You can only use `--delete' on an archive if the archive device allows you to write to any point on the media.
Warning: Don't try to delete an archive member from a magnetic tape, lest you scramble the archive. There is no safe way (except by completely re-writing the archive) to delete files from most kinds of magnetic tape.
@FIXME{How about automatic detection of archive media? Give error unless the archive device is either an ordinary file or different input and output (--file=-).}
@UNREVISED
The `--list' (`-t') option will list the names of members of the archive.
Name the members to be listed on the command line (to modify the
way these names are interpreted, see section Choosing Files and Names for tar). If you name no
members, then `--list' (`-t') will list the names of all the members of
the archive.
To see more than just the names of the members, use the `--verbose' (`-v')
option to cause tar to print out a listing similar to that of
`ls -l'.
Listing the Contents of an Archive
`--list' (`-t') prints a list of the file names of the archive members on the standard output. If you specify file name arguments on the command line (or using the `--files-from=file-of-names' (`-T file-of-names') option, see section Reading Names from a File), only the files you specify will be listed, and only if they exist in the archive. Files not specified will be ignored, unless they are under a specific directory.
If you include the `--verbose' (`-v') option, tar prints an
`ls -l' type listing for the archive. See section Checking tar progress, for a
description of the `--verbose' (`-v') option.
If the blocking factor of the archive differs from the default,
tar reports this. @FIXME-xref{Blocking Factor}.
See section Options to Help Read Archives, for a list of options which can be used to modify `--list' (`-t')'s operation.
This example prints a list of the archive members of the archive `stooges':
tar --list --file=stooges
tar responds:
larry moe shemp marx/julius marx/alexander marx/karl
This example generates a verbose list of the archive members of the archive file `dwarves', which has a blocking factor of two:
tar --list -v --file=blocks
tar responds:
tar: Blocksize = 2 blocks -rw------- ringo/user 42 May 1 13:29 1990 .bashful -rw-rw-rw- ringo/user 42 Oct 4 13:29 1990 doc -rw-rw-rw- ringo/user 42 Jul 20 18:01 1969 dopey -rw-rw---- ringo/user 42 Nov 26 13:42 1963 grumpy -rw-rw-rw- ringo/user 42 May 5 13:29 1990 happy -rw-rw-rw- ringo/user 42 May 1 12:00 1868 sleepy -rw-rw-rw- ringo/user 42 Jul 4 17:29 1776 sneezy
@UNREVISED
Use `--extract' (`-x') or `--get' to extract members from an archive. For each member named (or for the entire archive if no members are named) on the command line--or with `--files-from=file-of-names' (`-T file-of-names')---the a file is created with the contents of the archive member. The name of the file is the same as the member name.
Various options cause tar to extract more than just file
contents, such as the owner, the permissions, the modification date, and
so forth.
@FIXME{begin}
The `--same-permissions' (`-p') or `--preserve-permissions' options
cause tar to cause the new file to have the same permissions as
the original file did when it was placed in the archive. Without this
option, the current umask is used to affect the permissions.
When extrating, tar normally sets the modification time of the
file to the value recorded in the archive. The
`--touch' (`-m') option causes tar to omit doing this.
@FIXME{end}
To read archive members from the archive and write them into the file system, use `--extract' (`-x'). The archive itself is left unchanged.
If you do not specify the files to extract, tar extracts all
the files in the archive. If you specify the name of a directory as
a file name argument, tar will extract all files which have
been stored as part of that directory. If a file was stored with
a directory name as part of its file name, and that directory does
not exist under the working directory when the file is extracted,
tar will create the directory. @FIXME-xref{Selecting Archive
Members}, for information on specifying files to extract.
The following example shows the extraction of the archive `stooges' into an empty directory:
tar --extract --file=stooges
Generating a listing of the directory (`ls') produces:
larry moe shemp marx
The subdirectory `marx' contains the files `julius', `alexander' and `karl'.
If you wanted to just extract the files in the subdirectory `marx', you could specify that directory as a file name argument in conjunction with the `--extract' (`-x') operation:
tar --extract --file=stooges marx
Warning: Extraction can overwrite files in the file system. To avoid losing files in the file system when extracting files from the archive with the same name, use the `--keep-old-files' (`-k') option. See section Changing How
tarWrites Files.
If the archive was created using `--blocking-factor=512-size' (`-b 512-size'), `--compress' (`-Z') or `--multi-volume' (`-M'), you must specify those format options again when extracting files from the archive (see section Controlling the Archive Format).
@FIXME{each option wants its own node. summary after menu}
Normally, tar will request data in full record increments from
an archive storage device. If the device cannot return a full record,
tar will report an error. However, some devices do not always
return full records, or do not require the last record of an archive to
be padded out to the next record boundary. To keep reading until you
obtain a full record, or to accept an incomplete record if it contains
an end-of-archive marker, specify the `--read-full-records' (`-B') option
in conjunction with the `--extract' (`-x') or `--list' (`-t') operations.
See section Listing Archive Members.
The `--read-full-records' (`-B') option is turned on by default when
tar reads an archive from standard input, or from a remote
machine. This is because on BSD Unix systems, attempting to read a
pipe returns however much happens to be in the pipe, even if it is
less than was requested. If this option were not enabled, tar
would fail as soon as it read an incomplete record from the pipe.
If you're not sure of the blocking factor of an archive, you can read the archive by specifying `--read-full-records' (`-B') and `--blocking-factor=512-size' (`-b 512-size'), using a blocking factor larger than what the archive uses. This lets you avoid having to determine the blocking factor of an archive. @FIXME-xref{Blocking Factor}.
Normally tar stops reading when it encounters a block of zeros
between file entries (which usually indicates the end of the archive).
`--ignore-zeros' (`-i') allows tar to completely read an archive
which contains a block of zeros before the end (i.e. a damaged
archive, or one which was created by cat-ing several archives
together).
The `--ignore-zeros' (`-i') option is turned off by default because many
versions of tar write garbage after the end-of-archive entry,
since that part of the media is never supposed to be read. GNU
tar does not write after the end of an archive, but seeks to
maintain compatablity among archiving utilities.
If you are using a machine with a small amount of memory, and you
need to process large list of file names, you can reduce the amount
of space tar needs to process the list. To do so, specify the
`--same-order' (`-s') option and provide an ordered list of file names.
This option tells tar that the name arguments provided
on the command line, or read from a file using the `--files-from=file-of-names' (`-T file-of-names')
option, are listed in the same order as the files in the archive.
You can create a file containing an ordered list of files in the archive by storing the output produced by `tar --list --file=archive-name'. See section Listing Archive Members, for information on the `--list' (`-t') operation.
This option is probably never needed on modern computer systems.
@FIXME{we don't need/want --preserve to exist any more}
tar Writes Files@FIXME{find a better title} @UNREVISED
Normally, tar writes extracted files into the file system
without regard to the files already on the system--files with the same
name as archive members are overwritten. If a symbolic link already
exists by the name of the file to extract, the file pointed to by the
symbolic link is overwritten instead of the symbolic link itself if
this is possible. As for special devices, empty directories, etc.,
and even symbolic links, they are removed if they are found to be on
the way of the proper extraction.
On the safe side, to prevent tar from extracting an archive
member from an archive, if doing so will overwrite a file in the
file system, use `--keep-old-files' (`-k') in conjunction with the
`--extract' (`-x') operation. When this option is specified, tar
reports an error stating the name of the files in conflict, instead
of writing the file from the archive.
On the aggressive side, the `--unlink-first' (`-U') option removes existing files, symbolic links, empty directories, devices, etc., prior to extracting over them. In particular, using this option will prevent following an already existing symbolic link by the name of an extracted file, since the link itself is removed prior to the extraction, rather than the file it points to. The `--unlink-first' (`-U') option might also be required to prevent segmentation violations or other woes when extracting arbitrary executables over copies currently running, because on some systems, the backing store for the executable is the original text. However, using this option, if something goes wrong with the extraction, you might end up with no file at all.
On the very aggressive side, by specifying the `--unlink-first' (`-U') option more than once, anything that is preventing the extraction of a file would be removed as far as current permissions allow it, would it mean the full recursive removal of the contents of a non-empty directory. We insist that someone carelessly using this feature may have very bad surprises. You were warned!
tar from over-writing
existing files with files with the same name from the archive.
The `--keep-old-files' (`-k') option is meaningless with `--list' (`-t').
Prevents tar from overwriting files in the file system during
extraction.
Normally, tar sets the modification times of extracted files to
the modification times recorded for the files in the archive, but
limits the permissions of extracted files by the current umask
setting.
To set the modification times of extracted files to the time when the files were extracted, use the `--touch' (`-m') option in conjunction with `--extract' (`-x').
To set the modes (access permissions) of extracted files to those recorded for those files in the archive, use the option in conjunction with the `--extract' (`-x') operation. @FIXME{Should be aliased to ignore-umask.}
@FIXME{Following paragraph needs to be rewritten: why doesnt' this cat files together, why is this useful. is it really useful with more than one file?}
To write the files extracted to the standard output, instead of creating the files on the file system, use `--to-stdout' (`-O') in conjunction with `--extract' (`-x'). This option is useful if you are extracting files to send them through a pipe, and do not need to preserve them in the file system.
tar writes
the contents of the files extracted to its standard output. This may
be useful if you are only extracting the files in order to send them
through a pipe. This option is meaningless with `--list' (`-t').
@FIXME{Why would you want to do such a thing, how are files separated on the standard output? is this useful with more that one file? Are pipes the real reason?}
The `--starting-file=name' (`-K name') option causes tar to begin
extracting or listing the archive with the file filename, and
to consider only the files starting at that point in the archive.
This is useful if a previous attempt to extract files failed when
it reached filename due to lack of free space. (Assuming, of
course, that there is now free space, or that you are now extracting
into a different file system.)
If a previous attempt to extract files failed due to lack of disk space, you can use `--starting-file=name' (`-K name') to start extracting only after file name when extracting files from the archive. This assumes, of course, that there is now free space, or that you are now extracting into a different file system.
If you notice you are running out of disk space during an extraction
operation, you can also suspend tar, remove unnecessary
files from the file system, and then restart the same tar
operation. In this case, `--starting-file=name' (`-K name') is not necessary.
@FIXME-xref{incremental}, See section Asking for Confirmation During Operations, and section Excluding Some Files.
The `--same-order' (`-s') option tells tar that the list of file
names to be listed or extracted is sorted in the same order as the
files in the archive. This allows a large list of names to be used,
even on a small machine that would not otherwise be able to hold all
the names in memory at the same time. Such a sorted list can easily be
created by running `tar -t' on the archive and editing its output.
This option is probably never needed on modern computer systems.
The `--compare' (`-d') or `--diff' option compares the contents of the specified archive members against the files with the same names, and reports its findings. If no members are named on the command line, or through `--files-from=file-of-names' (`-T file-of-names'), then the entire archive is so compared.
Some format parameters must be taken into consideration when modifying an archive: @FIXME{???}.
Compressed archives cannot be modified.
You have to specify the record size of the archive when modifying an archive with a non-default record size.
Multi-volume archives can be modified like any other archive. To add files to a multi-volume archive, you need to only mount the last volume of the archive media (and new volumes, if needed). For all other operations, you need to use the entire archive.
If a multi-volume archive was labeled using `--label=archive-label' (`-V archive-label')
(see section Including a Label in the Archive) when it was created, tar will not automatically
label volumes which are added later. To label subsequent volumes,
specify `--label=archive-label' (`-V archive-label') again in conjunction with the `--append' (`-r'),
`--update' (`-u') or `--concatenate' (`-A') operation.
@FIXME{example}
`--compare' (`-d') compares archive members in an existing archive
with their counterparts in the file system, and reports differences in
file size, mode, owner, modification date and contents. If a file is
represented in the archive but does not exist in the file system,
tar reports a difference.
If you use file name arguments in conjunction with `tar
--compare', tar compares the archived versions of the files
specified with their counterparts in the file system. If you specify
a file that is not in the archive, tar will report an error. If
you don't specify any files, tar compares all the files in the
archive.
Because tar only checks files in the archive against files in
the file system, and not vice versa, it ignores files in the file
system that do not exist in the archive.
The following example compares the archive members `larry', `moe' and `curly' in the archive `stooges' with files of the same name in the file system.
tar --compare --file=stooges larry moe curly
If a file, for example `curly', did not exist in the archive,
tar would report an error, as follows:
curly: does not exist
@FIXME-xref{somewhere, for more information about format parameters.}