(tar)Basic tar Operations

Specifying Names to tar

Invoking tar

Top

Basic `tar' Operations
**********************

     *(This message will disappear, once this node revised.)*

   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:

   * Add files to an existing archive--`--append' (`-r').

   * Compare files in an archive with files in the file
     system--`--compare' (`-d') or `--diff'.

   * Add archives to another archive--`--concatenate' (`-A').

   * Create an archive--`--create' (`-c').

   * Delete files from an archive--`--delete'.

   * Extract files from an archive--`--extract' (`-x') or `--get'.

   * List the files in an archive--`--list' (`-t').

   * Update an archive by appending newer versions of already stored
     files--`--update' (`-u').

FIXME: xref Reading and Writing
   , 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.

`--create'
`-c'
     Create a new archive

`--catenate'
`--concatenate'
`-A'
     Add the contents of one or more archives to another archive

`--append'
`-a'
     Add files to an existing archive

`--list'
`-t'
     List the members in an archive

`--delete'
     Delete members from an archive

`--extract'
`--get'
`-x'
     Extract members from an archive

`--compare'
`--diff'
`-d'
     Compare members in an archive with files in the file system

`--update'
`-u'
     Update an archive by appending newer versions of already stored
     files

   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 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.
The other operations of `tar' (`--list' (`-t'), `--extract' (`-x'),
`--compare' (`-d'), and `--update' (`-u')) will act on the entire
contents of the archive.

   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.

`-A'
     Adds copies of an archive or archives to the end of another
     archive.

`-c'
     Creates a new archive.

`-d'
     Compares files in the archive with their counterparts in the file
     system, and reports differences in file size, mode, owner,
     modification date and contents.

`-r'
     Adds files to the end of the archive.

`-t'
     Prints a list of the contents of the archive.

`-x'
     Reads files from the archive and writes them into the active file
     system.

`-u'
     Adds files to the end of the archive, but only if they are newer
     than their counterparts already in the archive, or if they do not
     already exist in the archive.

`--catenate'
     Adds copies of an archive or archives to the end of another
     archive.

`--append'
     Adds files to the end of the archive.

`--append'
     Adds files to the end of the archive.

`--catenate'
     Adds copies of an archive or archives to the end of another
     archive.

`--compare'
     Compares files in the archive with their counterparts in the file
     system, and reports differences in file size, mode, owner,
     modification date and contents.

`--concatenate'
     Adds copies of an archive or archives to the end of another
     archive.

`--create'
     Creates a new archive.

`--delete'
     Deletes files from the archive.  All versions of the files are
     deleted.

`--diff'
     Compares files in the archive with their counterparts in the file
     system, and reports differences in file size, mode, owner,
     modification date and contents.

`--extract'
     Reads files from the archive and writes them into the active file
     system.

`--get'
     Reads files from the archive and writes them into the active file
     system.

`--list'
     Prints a list of the contents of the archive.

`--update'
     Adds files to the end of the archive, but only if they are newer
     than their counterparts already in the archive, or if they do not
     already exist in the archive.

`--version'
     Prints the version number of the `tar' program to the standard
     error.

   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 (
FIXME: pxref Invoking 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'
     Create a new archive.

     This command tells `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'
     Extract files from an archive.

     This command causes `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'
     List the contents of an archive.

     This command causes `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'
     Find differences between an archive and the corresponding online
     files.

     This command causes `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'
     Append files to the end of an archive.

     This command causes `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'
     Only append files newer than the version in an archive.

     This command causes `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'
     Append existing archives to another archive.

     This command is used for concatenating several archive files into
     one big archive file.  The files to operate on should all be
     archive files.  They are all appended to the end of the archive
     file which `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'
     Delete from the archive (not on tapes!).

     This command causes `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 (
FIXME: pxref Invoking 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.

   Modifying Archives

   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'.
FIXME: xref Listing Contents
   .

Creating a New Archive

Adding to an Existing Archive

Updating an Archive

Combining Archives

Removing Archive Members

Listing Archive Members

Extracting Archive Members

Comparing Archives Members with Files

Matching Format Parameters