tar
This chapter guides you through some basic examples of tar
operations. If you already know how to use some other version of
tar, then you probably don't need to read this chapter. This
chapter omits complicated details about many of the ways tar
works. See later chapters for full information.
Before proceeding further with this tutorial chapter, be sure you
understand already and clearly what is meant by "archive" and
"archive member". See section What tar Does.
This chapter guides you through some basic examples of tar
operations. In the examples, the lines you should type are preceded by
a `%', which is a typical shell prompt. We use mnemonic forms of
operations and options in the examples, and in discussions in the text,
but short forms produce the same result.
Most of the options to tar come in both long forms and short
forms. The options described in this tutorial have the following
abbreviations (except `--delete', which has no shorthand form):
These options make typing long tar commands easier. For example,
instead of typing
tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus
you can type
tar -c -f /tmp/afiles.tar -v apple angst asparagus
For more information on option syntax, section Invoking GNU tar.
In discussions in the text, when we present some mnemonic option, we
also give the corresponding short option within parentheses.
@UNREVISED
To create a new archive, use the `--create' (`-c') option to tar.
You can use options to specify the name and format of the archive (as
well as other characteristics), and you can use file name arguments
to specify which files and directories are to be put in the archive.
See section Creating a New Archive, for more information about the `--create' (`-c')
operation.
To create a new archive, use the `--create' (`-c') option to tar.
You should generally use the `--file=archive-name' (`-f archive-name') option to specify the name
the tar archive will have. Then specify the names of the
files you wish to place in the new archive. For example, to place
the files `apple', `angst', and `asparagus' into an
archive named `afiles.tar', use the following command:
tar --create --file=afiles.tar apple angst asparagus
The order of the arguments is not important when using mnemonic option style. You could also say:
tar apple --create angst --file=afiles.tar asparagus
However, this order is harder to understand. In this manual, we will list the arguments in an order that makes the commands easier to understand, but you can type them in any order you wish.
Whenever you use `--create' (`-c'), tar will erase the current
contents of the file named by `--file=archive-name' (`-f archive-name') if it exists. To add
files to an existing archive, you need to use a different option.
See section Adding to an Existing Archive, for information on how to do this. When an archive is
created through `--create' (`-c'), the member names of the members of
the archive are exactly the same as the file names as you typed them
in the tar command. So, the member names of `afiles' (as
created by the first example above) are `apple', `angst',
and `asparagus'. However, suppose an archive were created with
this command:
tar --create --file=bfiles.tar ./balloons baboon ./bodacious
Then, the three files `balloons', `baboon', and `bodacious' would get placed in the archive (because `./' is a synonym for the current directory), but their member names would be `./balloons', `baboon', and `./bodacious'.
If you want to see the progress of tar as it writes files into the
archive, you can use the `--verbose' (`-v') option.
If one of the files named with `--create' (`-c') is a directory, then
the operation of tar is more complicated. See section How to Archive Directories, for more information.
If you don't specify the `--file=archive-name' (`-f archive-name') option, then tar will use
a default. Usually this default is some physical tape drive attached to
your machine. If there is no tape drive attached, or the default is not
meaningful, then tar will print an error message. This error message
might look roughly like one of the following:
tar: can't open /dev/rmt8 : No such device or address tar: can't open /dev/rsmt0 : I/O error
If you get an error like this, mentioning a file you didn't specify
(`/dev/rmt8' or `/dev/rsmt0' in the examples above), then tar
is using a default value for `--file=archive-name' (`-f archive-name'). You should generally specify a
`--file=archive-name' (`-f archive-name') argument whenever you use tar, rather than relying
on a default.
To create a new archive, use the `--create' (`-c') option to
tar. You can use options to specify the name and format of
the archive (as well as other characteristics), and you can use
file name arguments to specify which files to put in the archive.
If you don't use any options or file name arguments, tar will
use default values. See section Creating a New Archive, for more information
about the `--create' (`-c') option.
@UNREVISED
This example shows you how to create an archive file in your working
directory containing other files in the same directory. The three
files you archive in this example are called `blues',
`folk', and `jazz'. The archive file is called
`collection'. While the archive in this example is written to the
file system, it could also be written to tape. (If you want to follow
along with this and future examples, create a practice subdirectory
containing files with these names. To create the directory, type
`mkdir practice' at the system prompt. You can create the files
using a text editor, such as emacs).
While in the directory containing the files you want to archive, list the directory's contents.
Type:
% cd practice % ls
The system responds:
blues folk jazz %
This is to check that the files to be archived do in fact exist in the
working directory, and to check that the archive name you have chosen
isn't already in use. If it is, tar will overwrite the old
archive and its contents will be lost.
Then,
tar.
tar will write the archive to
the default storage device, which varies from system to system.
tar will archive everything in the
working directory.
Type:
% tar --create --file=collection blues folk jazz
If you now list the contents of the working directory (`ls'), you will find the archive file listed as well as the files you saw previously.
% ls blues folk jazz collection %
This example shows you how to create an archive file in the working directory containing other files in the working directory. The three files you archive in this example are called `blues', `folk', and `jazz'. The archive file is called `collection'. While the archive in this example is written to the file system, it could also be written to any other device.
(If you want to follow along with this and future examples, create a directory called `practice' containing files called `blues', `folk' and `jazz'. To create the directory, type `mkdir practice' at the system prompt. It will probably be easiest to create the files using a text editor, such as Emacs.)
First, change into the directory containing the files you want to archive:
% cd practice
`~/practice' is now your working directory.
Then, check that the files to be archived do in fact exist in the
working directory, and make sure there isn't already a file in the
working directory with the archive name you intend to use. If you
specify an archive file name that is already in use, tar will
overwrite the old file and its contents will be lost.
To list the names of files in the working directory, type:
% ls
The system responds:
blues folk jazz %
Then,
tar.
tar will write the archive to the
default storage device, which may vary from system to system and from
tar to tar. In doubt, it is safer to always specify it.
tar interprets archive file names relative to the working
directory. Make sure you have write access to the working
directory before using tar.
tar interprets
file names relative to the working directory). If you don't use
any name arguments, tar will archive everything in the
working directory.
Type:
% tar --create --file=collection blues folk jazz
If you now list the contents of the working directory (`ls'), you will find the archive file listed as well as the files you saw previously.
% ls blues folk jazz collection %
tar in Verbose Mode@UNREVISED
If you include the `--verbose' (`-v') option on the command
line, tar will list the files it is acting on as it is working.
The example above in verbose mode would be:
% tar --create --file=collection --verbose blues folk jazz blues folk jazz
The first line, which is preceeded by a `%', is the command line.
The lines after the first line are generated by tar as it
works. In the following examples we usually use verbose mode, though
it is almost never required.
If you include the `--verbose' (`-v') option on the command line,
tar will list the files it is acting on as it is working. In verbose
mode, the creation example above would appear as:
% tar --create --file=collection --verbose blues folk jazz blues folk jazz
The first line is the command typed in by the user. The remaining
lines are generated by tar. In the following examples we usually use
verbose mode, though it is almost never required.
@UNREVISED
When the names of files or members specify directories, the operation of
tar is more complex. Generally, when a directory is named,
tar also operates on all the contents of the directory,
recursively. Thus, to tar, the file name `/' names the
entire file system.
To archive the entire contents of a directory, use `--create' (`-c') or `--append' (`-r') as usual, and specify the name of the directory. For example, to archive all the contents of the current directory, use `tar --create --file=archive-name .'. Doing this will give the archive members names starting with `./'. To archive the contents of a directory named `foodir', use `tar --create --file=archive-name foodir'. In this case, the member names will all start with `foodir/'.
If you give tar a command such as `tar --create
--file=foo.tar .', it will report `tar: foo.tar is the archive;
not dumped'. This happens because the archive `foo.tar' is
created before putting any files into it. Then, when tar
attempts to add all the files in the directory `.' to the archive,
it notices that the file `foo.tar' is the same as the archive,
and skips it. (It makes no sense to put an archive into itself.)
GNU tar will continue in this case, and create the archive as
normal, except for the exclusion of that one file. Other versions of
tar, however, are not so clever, and will enter an infinite
loop when this happens, so you should not depend on this behavior.
In general, make sure that the archive is not inside a directory
being dumped.
When extracting files, you can also name directory archive members on
the command line. In this case, tar extracts all the archive
members whose names begin with the name of the directory. As usual,
tar is not particularly clever about interpreting member names.
The command `tar --extract --file=archive-name .' will not
extract all the contents of the archive, but only those members whose
member names begin with `./'.
You can archive a directory by specifying its directory name as a
file name argument to tar. The files in the directory will be
archived relative to the working directory, and the directory will be
re-created along with its contents when the archive is extracted.
To archive a directory, first move to its superior directory. If you have been following the tutorial, you should type:
% cd .. %
Once in the superior directory, you can specify the subdirectory as a file name argument. To store the directory `practice' in the archive file `music', type:
% tar --create --verbose --file=music practice
tar should output:
practice/ practice/blues practice/folk practice/jazz practice/collection
Note that the archive thus created is not in the subdirectory
`practice', but rather in the working directory--the directory
from which tar was invoked. Before trying to archive a
directory from its superior directory, you should make sure you
have write access to the superior directory itself, not only the
directory you are trying archive with tar. Trying to store
your home directory in an archive by invoking tar from the root
directory will probably not work. See section Absolute File Names. (Note also that
`collection', the original archive file, has itself been archived.
tar will accept any file as a file to be archived, regardless
of its content. When `music' is extracted, the archive file
`collection' will be re-written into the file system).
You can store a directory in an archive by using the directory name as
a file name argument to tar. When you specify a directory file,
tar archives the directory file and all the files it contains.
The names of the directory and the files it contains are stored in the
archive relative to the current working directory--when the directory
is extracted they will be written into the file system relative to
the working directory at that time. See section Absolute File Names. To archive a
directory, first move to its superior directory. If you have been
following the tutorial, you should type:
% cd .. %
Once in the superior directory, specify the subdirectory using a file name argument. To store the directory file `~/practice' in the archive file `music', type:
% tar --create --verbose --file=music practice
tar should respond:
practice/ practice/blues practice/folk practice/jazz practice/collection
Note that `~/practice/collection', another archive file, has
itself been archived. tar will accept any file as a file to
be archived, even an archive file.
@UNREVISED
While the `--list' (`-t') operation with the `--verbose' (`-v') option
specified is useful in keeping files in the archive current with files
in the file system (by allowing the user to compare size and
modification dates), it is simpler to have tar itself compare
file attributes and report back on file differences. To do so, use
the `--compare' (`-d') or `--diff' operation.
The `--compare' (`-d') operation, as its name implies, causes tar
to compare files and directories in the archive with their
counterparts (files of the same name) in the file system, and report
back differences in file size, mode, owner and modification date.
When performing the `--compare' (`-d') operation, tar acts only on
files actually in the archive--it will ignore files in the active
file system that do not exist in the archive. If tar with
`--compare' (`-d') specified is given, as a file name argument, the name
of a file that does not exist in the archive, it will return an error
message.
To compare the files in the practice directory with their counterparts in the archive file `collection', in the same directory, you would, while in the `practice' directory:
tar and specify the operation to compare files in the
archive with their counterparts in the file system---`--compare' (`-d')
or `--diff'.
% tar --compare --file=collection %
While it looks like nothing has happened, tar has, in fact,
done the comparison--and found nothing to report. The same example
with the `--verbose' (`-v') option specified would list the files in the
archive as they are being compared with their counterparts of the same
name:
% tar --compare --verbose --file=collection blues folk jazz %
If tar had had anything to report, it would have done so as it
was comparing each file. If you remove the file `jazz' from the
file system (`rm jazz'), and modify the file `blues' (for
instance, by adding text to it with a text editor), the above example
would look like:
% tar --compare --verbose --file=collection blues blues: mod time differs blues: size differs folk jazz jazz: does not exist %
You should note again that while `--compare' (`-d') does cause tar
to report back on files in the archive that do not exist in the file
system, tar will ignore files in the active file system that do
not exist in the archive. To demonstrate this, create a file in the
`practice' directory called `rock' (using any text editor).
If you generate a directory listing the new file will appear.
% ls blues folk collection rock
If you run the `--compare' (`-d') example again you will obtain the following:
% tar --compare --verbose --file=collection blues blues: mod time differs blues: size differs folk jazz jazz: does not exist %
tar ignores the file `rock' because tar is
comparing files in the archive to files in the file system, not vice
versa. If `rock' had been passed to tar explicitly (as a
file name argument), tar would have returned an error message,
as follows:
% tar --compare --verbose --file=collection rock tar: rock not found in archive %
To compare the attributes of archive members with the attributes of
their counterparts in the file system, use the `--compare' (`-d') or
`--diff'operation. While you could use `--list --verbose'
(`-tv') to compare visually, yourself, some file attributes,
it is simpler to have tar itself compare file attributes and
report back on file differences.
The `--compare' (`-d') operation, as its name implies, compares
archive members with files of the same name in the file system, and
reports back differences in file size, mode, owner and modification
date. `tar +compare' acts only on archive members--it ignores
files in the file system that are not stored in the archive.
If you give with `--compare' (`-d') a name argument that does not
correspond to the name of an archive member, tar responds with
an error message.
To compare archive members in the archive file `collection' with files in the `~/practice' directory, first change into the `practice' directory. Then:
tar and specify the `--compare' (`-d')
operation---`--compare' (`-d') or `--diff'.
% tar --compare --file=collection %
While it looks like nothing has happened, tar has, in fact, done the
comparison--and found nothing to report.
Use the `--verbose' (`-v') option to list the names of archive members as they are being compared with their counterparts of the same name in the file system:
% tar --compare --verbose --file=collection blues folk jazz %
If tar had had anything to report, it would have done so as it was
comparing each file.
If you remove the file `jazz' from the file system (`rm jazz'), and modify the file `blues' (for instance, by adding text to it with an editor such as Emacs), the above example would look like:
% tar --compare --verbose --file=collection blues blues: mod time differs blues: size differs folk jazz jazz: does not exist %
Note again that while `--compare' (`-d') reports the names of archive members that do not have counterparts in the file system, `--compare' (`-d') ignores files in the file system that do not have counterparts in the archive. To demonstrate this, create a file in the `practice' directory called `rock' (using any text editor). The new file appears when you list the directory's contents:
@FIXME{Given an example}
@UNREVISED
In addition to using `--compare' (`-d') to compare individual files in an archive with their counterparts in the file system, you can use `--compare' (`-d') to compare archived directories with their counterparts in the active file system. You could re-create the examples above using your home directory as the working directory, and using the archive file `music' (in which is stored the `practice' directory) instead of the archive file `collection'.
First, change into the home directory (`cd ..'). Then, try the above example using `music' as the specified archive file, and the `practice' subdirectory as a file name argument.
% tar --compare --verbose --file=music practice practice practice/blues practice/blues: mod time differs practice/blues: size differs practice/folk practice/jazz practice/jazz: does not exist practice/collection
In addition to using `--compare' (`-d') to compare text files, you can use `--compare' (`-d') to compare directories. To illustrate this, re-create the examples above using your home directory as the working directory, and using the archive file `~/music' instead of the archive file `~/practice/collection'.
First, change into your home directory (`cd ~'). Then, try the above example using `music' as the specified archive file, and `practice' as a file name argument.
% tar --compare --verbose --file=music practice
If you have been following along with the tutorial, tar will respond:
practice practice/blues practice/blues: mod time differs practice/blues: size differs practice/folk practice/jazz practice/jazz: does not exist practice/collection
@UNREVISED
Use `--list' (`-t') to print the names of members stored in an
archive. Use a `--file=archive-name' (`-f archive-name') option just as with
`--create' (`-c') to
specify the name of the archive. For example, the archive
`afiles.tar' created in the last section could be examined with the
command `tar --list --file=afiles.tar'. The output of tar would
then be:
apple angst asparagus
The archive `bfiles.tar' would list as follows:
./baloons baboon ./bodacious
(Of course, `tar --list --file=empty-archive.tar' would produce no output.)
If you use the `--verbose' (`-v') option with `--list' (`-t'), then tar will print out a listing reminiscent of
`ls -l', showing owner, file size, and so forth.
You can also specify member names when using `--list' (`-t').
In this case, tar will only list the names of members you
identify. For example, `tar --list --file=afiles.tar apple'
would only print `apple'. It is essential when specifying
member names to tar that you give the exact member names.
For example, `tar --list --file=bfiles baloons' would produce
no output, because there is no member named `baloons', only
one named `./baloons'. While the file names `baloons' and
`./baloons' name the same file, member names are compared using
a simplistic name comparison, in which an exact match is necessary.
@UNREVISED
You can list the contents of the archive you just created with
another option of tar: `--list' (`-t'). To list the contents of
an archive, type:
% tar --list --file=collection
tar will respond:
blues folk jazz
You can use `--list' (`-t') to output a list of the files in an archive.
If you use file name arguments with this operation, tar will
look in the archive for the files specified and display their names
only if they are, in fact, stored. You can use `--list' (`-t') with
the `--verbose' (`-v') option to find out the attributes (owner, size,
etc.) of stored files.
You can list the contents of an archive with another operation of
tar: `--list' (`-t'). To list the contents of the archive you
just created, type:
% tar --list --file=collection
tar will respond:
blues folk jazz
See section Listing Archive Members, for more information about the `--list' (`-t') operation.
In a previous example, you created the archive `music' in the home directory. To list the contents of `music':
tar.
Thus:
% tar --list --file=music practice/ practice/blues practice/folk practice/jazz practice/collection
Use `--list' (`-t') to print the names of files stored in an archive.
If you use file name arguments with this operation, tar prints
the names of the specified files if they are stored in the archive.
If you use a directory name as a file name argument, tar also
prints the names of all underlying files, including sub-directories.
If you use no file name arguments, tar prints the names of
all the archive members.
You can use `--list' (`-t') with the `--verbose' (`-v') option to print archive members' attributes (owner, size, etc.).
To list the names of files stored in an archive, use the `--list' (`-t') operation of tar.
In a previous example, you created the archive `~/music'. To list the contents of `music', while in your home directory:
tar.
Thus:
% tar --list --file=music practice/ practice/blues practice/folk practice/jazz practice/collection
@UNREVISED
When you specify the `--verbose' (`-v') option in conjunction with
`--list' (`-t'), tar will print additional information about
the files being listed (file protection, owner and group ID, size, and
date and time of creation). The example above, in verbose mode, would
be:
% tar --list --verbose --file=music drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/ -rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues -rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk -rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz -rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/collection %
Note that using `--verbose' (`-v') with `--list' (`-t') does not cause tar to print the names of files
as they are being acted on, though the `--verbose' (`-v')
option will have this effect with all other operations.
To get more information when you list the names of files stored in an archive, specify the `--verbose' (`-v') option in conjunction with `--list' (`-t').
tar will print archive member's file protection, owner and group ID,
size, and date and time of creation.
For example:
% tar --list --verbose --file=music drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/ -rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues -rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk -rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz -rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/collection %
Note that when you use `--verbose' (`-v') with `--list' (`-t'), tar doesn't print the names of files as they are
being acted on, though the `--verbose' (`-v') option will
have this effect when used with all other operations.
@UNREVISED
To to see if a particular file is in an archive, specify the name of the file in question as a file name argument while specifying the `--list' (`-t') operation. For example, if you wanted to see if the file `folk' were in the archive file `music', you would:
tar, and specify the operation to list the contents of
an archive---`--list' (`-t').
tar is to look for, as a file
name argument. Because tar preserves paths, file names must
be specified as they appear in the archive (ie.. as they are relative
to the directory from which the archive was created). See section Absolute File Names.
Type:
% tar --list --file=music practice/folk
tar responds:
practice/folk
If the file were not in the archive (for example, the file `practice/rock'), the example above would look like:
% tar --list --file=music practice/rock tar: practice/rock not found in archive
The `--verbose' (`-v') option does not have any effect on execution of the `--list' (`-t') operation when you have specified file name arguments. @FIXME{Is this a bug?}
To to see if a particular file is in an archive, use the name of the file in question as a file name argument while specifying the `--list' (`-t') operation. For example, to see whether the file `folk' is in the archive file `music', do the following:
tar, and specify the `--list' (`-t') operation.
Type:
% tar --list --file=music practice/folk
tar responds:
practice/folk
If the file were not stored in the archive (for example, the file `practice/rock'), the example above would look like:
% tar --list --file=music practice/rock tar: practice/rock not found in archive
If you had used `--verbose' (`-v') mode, the example above would look like:
% tar --list --file=music practice/folk -rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
@UNREVISED
To get information about the contents of an archived directory, use the directory name as a file name argument in conjunction with `--list' (`-t'). To find out file attributes, include the `--verbose' (`-v') option.
For example, to find out about files in the directory `practice', in the archive file `music', type:
% tar --list --file=music practice
tar responds:
drwxrwxrwx myself/user 0 May 31 21:49 1990 practice/ -rw-rw-rw- myself/user 42 May 21 13:29 1990 practice/blues -rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk -rw-rw-rw- myself/user 40 May 21 13:30 1990 practice/jazz -rw-rw-rw- myself/user 10240 May 31 21:49 1990 practice/collection
When you use a directory name as a file name argument, tar acts on
all the files (including sub-directories) in that directory.
@UNREVISED
In order to extract members from an archive, use the `--extract' (`-x') option. Specify the name of the archive with `--file=archive-name' (`-f archive-name'). To extract specific archive members, give their member names as arguments. It essential to give their exact member name, as printed by `--list' (`-t'). This will create a copy of the archive member, with a file name the same as its name in the archive.
Keeping the example of the two archives created at the beginning of this tutorial, `tar --extract --file=afiles.tar apple' would create a file `apple' in the current directory with the contents of the archive member `apple'. It would remove any file named `apple' already present in the directory, but it would not change the archive in any way.
Remember that specifying the exact member name is important. `tar --extract --file=bfiles.tar baloons' will fail, because there is no member named `baloons'. To extract the member named `./baloons' you would need to specify `tar --extract --file=bfiles.tar ./baloons'. To find the exact member names of the members of an archive, use `--list' (`-t'). See section How to List Archives. If you do not list any archive member names, then `--extract' (`-x') will extract all the members of the archive.
If you give the `--verbose' (`-v') option, then `--extract' (`-x') will print the names of the archive members as it extracts them.
@UNREVISED
Obviously, the ultimate goal of tar users is to eventually get
their files back. To do this, use the `--extract' (`-x') or `--get'
operation. `--extract' (`-x') can be used to retrieve individual files
from an archive, or can be used to write all the files in the archive
back into the file system.
In the previous example you concatenated two archives, `music', and `practice/collection'. To now retrieve the complete contents of `music' (the target file in the concatenation process), you would, from the home directory:
tar and specify the operation to extract files from an
archive (`--extract' (`-x') or `--get'.
% tar --extract --file=music tar: Could not make directory practice : File exists
Because the files stored originally in `music' were stored as
files in a subdirectory (not as files in the working directory), they
are stored in the archive with a leading directory name---tar,
in restoring them, has tried to recreate that directory and failed:
the directory already exists. The extraction has not been aborted,
however. If you now change into the `practice' directory and
generate a directory listing, you will find that `jazz', which we
removed in an earlier example, has been resurrected.
% cd practice % ls blues classical folk jazz collection rock
If you look more closely at the files in the directory, however, you
will find that `blues' and `folk' are, in fact, the original
versions of the file, which were stored in `music' at the
beginning of the tutorial. tar, in extracting the original
files from `music', has overwritten the existing files in the
file system.
While the newer versions of the files were stored in `collection'
above, they can no longer be extracted from it. `collection' too
was archived by tar when the `practice' directory was
stored in the archive file `music', and was restored to its older
incarnation when the files in `practice' were overwritten.
However, the newer version of `collection' was concatenated with
`music'. The contents of the newer version of `collection',
therefore, should have been extracted when all the contents of
`music' were extracted. They were. tar has restored them
into the working directory using the names with which they were
originally stored. Because they were originally stored as part of
`collection', in the `practice' directory, they had no
preceeding directory stored as part of their file names. To find the
latest versions of `blues', `folk', `jazz', `rock'
and `classical', look in your home directory.
You may wish to restore the files in your `practice' directory to their last state before we extracted the files from `music'. Rather than moving the files from your home directory to the `practice' subdirectory, you can run the same extraction procedure as above using the `practice' subdirectory as your working directory:
% cd practice % tar --extract --verbose --file=~/music practice/ practice/blues practice/folk practice/jazz practice/collection blues folk jazz blues rock blues classical %
If you now examine the files in the practice directory, you will find that the files have been restored to their previous, newer, states. The old versions of the files, which were stored in `music' with a preceeding directory name, have been written into a newly created subdirectory under the working directory (which is your `practice' subdirectory). The new subdirectory is also called `practice'.
Creating an archive is only half the job--there would be no point in storing files in an archive if you couldn't retrieve them. To extract files from an archive, use the `--extract' (`-x') operation.
To extract specific files, use their names as file name arguments.
If you use a directory name as a file name argument, tar extracts all
the files (including subdirectories) in that directory. If you don't
use any file name arguments, tar extracts all the files in the
archive.
Note: tar will extract an archive member into the file system
without checking to see if there is already a file with the archive
member's file name. If there is a file with that name, tar
will overwrite that file and its contents will be lost.
See section Changing How tar Writes Files.
@UNREVISED
To extract specific files, specify them using file name arguments.
In an example above, you created the archive file `~/practice/collection', which contained the files `blues', `folk' and `jazz' in the `practice' directory. If, for some reason, you were to lose one of those text files (`rm ~/practice/blues'), you could extract it from the archive file.
First, change into the `practice' directory. Then,
tar and specify the `--extract' (`-x') or `--get'
operation.
tar extracts all the archive members)
% tar --extract --file=collection blues
If you list the contents of the directory, you will see that `blues' is back:
% ls folk jazz collection blues
@UNREVISED
To extract a directory and all the files it contains, use the
directory's name as a file name argument in conjunction with `tar
+extract'. Remember--tar stores and extracts file names relative to
the working directory.
In a previous example you stored the directory `~/practice'
in the archive file `~/music'. If you delete the contents of
`practice', you can restore them using tar.
First, change into the `practice' subdirectory (`cd ~/practice'). Then, remove all the files in `~/practice' (`rm *'). If you list the contents of the directory, you should now see that it is empty:
%ls %
Let's try to restore the contents of `practice' by extracting them from the archive file `~/music':
tar --extract --file=~/music practice
Now, list the contents of `practice' again:
%ls practice
What happened to the files? When you created `~/music', your
working directory was your home directory. When you extracted
`~/music', your working directory was `~/practice'. tar stored the
files in `practice' relative to your home directory, and then extracted
them relative to `~/practice'. The files are now in a new
subdirectory, called `~/practice/practice'.
To restore your files to their old positions, delete the new directory and its contents, and then redo the example above with your home directory as the working directory:
% rm ~/practice/practice/* % rmdir practice % cd .. % tar --extract --file=music practice
(tar will report that it is unable to create the directory
`~/practice' because it already exists. This will not effect the
extraction of the other archive members.)
@UNREVISED
If you want to add files to an existing archive, then don't use `--create' (`-c'). That will erase the archive and create a new one in its place. Instead, use `--append' (`-r'). The command `tar --append --file=afiles.tar arbalest' would add the file `arbalest' to the existing archive `afiles.tar'. The archive must already exist in order to use `--append' (`-r').
As with `--create' (`-c'), the member names of the newly added files will be the exact same as their names given on the command line. The `--verbose' (`-v') option will print out the names of the files as they are written into the archive.
If you add a file to an archive using `--append' (`-r') with the same name as an archive member already present in the archive, then the old member is not deleted. What does happen, however, is somewhat complex. @FIXME-xref{Multiple Members with the Same Name}. If you want to replace an archive member, use `--delete' first, and then use `--append' (`-r').
@FIXME{We want people to use the script for backups, so I an not going to use backups as an explanation in the tutorial. (people can still do it if they really want to)}
While you can use tar to create a new archive every time you want
to store a file, it is more sometimes efficient to add files to an
existing archive.
To add new files to an existing archive, use the `--append' (`-r') operation. To add newer versions of archive members to an archive, use the `--update' (`-u') operation.
While you can use tar to create an archive of an entire
directory or directory tree, it is more efficient when performing
backups to only archive those files which have been newly created or
changed since the last backup.
To add new files to an existing archive, or to add newer versions of old files, you can use the `--append' (`-r') operation, or the `--update' (`-u') operation.
@UNREVISED
The simplest method of adding a file to an already existing archive is the `--append' (`-r') operation, which writes the files specified into the archive without regard to whether or not they are already among the archived files. When you use `--append' (`-r') you must specify file name arguments, there is no default. If you specify a file that already exists in the archive another copy of the file will be added to the end of the archive anyway.
In the previous examples you created a file called `rock' in the practice directory which did not exist in either the archive file `collection', in the practice directory, or the archive file `music', in the home directory. To add `rock' to `collection', you would, while in the practice directory:
tar and specify the operation to add a
file---`--append' (`-r').
% tar --append --file=collection rock
If you now use the `--list' (`-t') operation, you will see that `rock' has been added to the archive:
% tar --list --file=collection blues folk jazz rock
While all newly created files have now been added to `collection', it is still not current with respect to the contents of the practice directory. If you recall from the examples using `--compare' (`-d') above, `blues' was changed after the archive `collection' was created. It is simple, however, to use `--append' (`-r') to correct the problem:
% tar --append --verbose --file=collection blues blues
Because you specified the `--verbose' (`-v') option, tar has
printed the name of the file being appended as it was acted on. If
you now use tar with the `--list' (`-t') option specified to get
the contents of the archive, you will optain the following:
% tar --list -f collection blues folk jazz rock blues
The newest version of `blues' is now at the end of the archive.
Because files are extracted from archives in the order in which they
appear in the archive, and because extracted files are given the same
names in the file system as they are stored under in the archive, when
the files in `collection' are extracted the newer version of
`blues' (which has the same name as the older) will overwrite the
version stored first. See section Changing How tar Writes Files.
@FIXME{--update wont take a directory argument if files that have been archived from that directory are now no longer in it. (I assume because it looks in the archive first for the directory listing.) this is a bug}
The simplest method of adding a file to an existing archive is
the `--append' (`-r') operation, which writes files into the archive
without regard to whether or not they are already archive members.
When you use `--append' (`-r') you must use file name arguments; there
is no default. If you specify a file that is already stored in the
archive, tar adds another copy of the file to the archive.
If you have been following the previous examples, you should have a text file called `~/practice/rock' which has not been stored in either the archive file `~/practice/collection', or the archive file `~/music'. To add `rock' to `collection', first make `practice' the working directory (`cd practice'). Then:
tar and specify the `--append' (`-r') operation.
For example:
% tar --append --file=collection rock
If you list the archive members in `collection', you will see that `rock' has been added to the archive:
% tar --list --file=collection blues folk jazz rock
@FIXME{this should be some kind of node.}
You can use `--append' (`-r') to keep archive members current with active files. Because `--append' (`-r') stores a file whether or not there is already an archive member with the same file name, you can use `--append' (`-r') to add newer versions of archive members to an archive. When you extract the file, 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.
If you recall from the examples using `--compare' (`-d') above, `blues' was changed after the archive `collection' was created. It is simple, however, to use `--append' (`-r') to add the new version of `blues' to `collection':
% tar --append --verbose --file=collection blues blues
If you now list the contents of the archive, you will obtain the following:
% tar --list -f collection blues folk jazz rock blues
The newest version of `blues' is at the end of the archive.
When the files in `collection' are extracted, the newer
version of `blues' (which has the same name as the older)
will overwrite the version stored first. When `--extract' (`-x') is
finished, only the newer version of `blues' is in the file system.
See section Changing How tar Writes Files.
@UNREVISED
While the `--append' (`-r') option is useful for updating files in an
archive, to keep an archive current with `--append' (`-r') you must
first use the `--compare' (`-d') or `--list' (`-t') options to determine
what files have been changed (or be willing to waste space by adding
identical copies of archived files to the ends of archives). It is
simpler to use the `--update' (`-u') operation, and let tar do
the work for you.
The `--update' (`-u') option causes tar to add files to the end
of an archive, just like the `--append' (`-r') option. When you invoke
tar with the `--update' (`-u') option specified you must specify
file name arguments. Unlike `--append' (`-r'), the `--update' (`-u') option
causes tar to check the archive to be updated to see if the
specified file is already stored. If the file (or one with the same
name) is already in the archive, tar checks the modification
date of the file in the archive and compares it to the file of the same
name in the file system. The file is only appended to the archive
if it is new or if its modification date has changed to a later one.
See section Operating Only on New Files. To see the `--update' (`-u') option at work, create a
new file, `classical', in your practice directory, and add a
line to the file `blues', using any text editor. Then invoke
tar with the `--update' (`-u') operation and the `--verbose' (`-v')
option specified, using the names of all the files in the practice
directory as file name arguments:
% tar --update --verbose --file=collection blues folk rock classical blues classical %
Because we have specified verbose mode, tar prints out the
names of the files it is working on, which in this case are the names
of the files that needed to be updated. If you now invoke tar
with the `--list' (`-t') operation specified, to generate a listing of
the files in the archive, you will see that `blues' and
`classical' have been added to its end.
[The reason tar does not overwrite the older file when updating
it is because writing to the middle of a section of tape is a difficult
process. Tapes are not designed to go backward. Even if they were,
imagine what would happen if the newer version were longer than the
older one.]
To keep archive members up to date with their counterparts of the
same name in the file system, use the `--update' (`-u') option.
This adds a specified file to an archive if no file of that
name is already stored in the archive. If there is already an archive
member with the same name, tar checks the modification date of the
archive member, and adds the file only if its modification date is
later. If a file is stored in the archive but no longer exists under
the same name in the active file system, tar reports an error.
You could use the `--append' (`-r') option to keep an archive current, but do so you would either have to use the `--compare' (`-d') and `--list' (`-t') options to determine what files needed to be re-archived (which could waste a lot of time), or you would have to be willing to add identical copies of already archived files to the archive (which could waste a lot of space).
You must use file name arguments with the `--update' (`-u') operation--if
you don't specify any files, tar won't act on any files.
To see the `--update' (`-u') option at work, create a new file,
`~/practice/classical', and modify the file `~/practice/blues' (you can
use a text editor, such as Emacs, to do both these things). Then, with
`practice' as your working directory, invoke tar with the
`--update' (`-u') option, using the
names of all the files in the practice directory as file name
arguments, and specifying the `--verbose' (`-v') option:
% tar --update --verbose --file=collection blues folk rock classical blues classical %
Because you specified verbose mode, tar printed out the names of the
files it acted on. If you now list the archive members of the archive,
(`tar --list --file=collection'), you will see that the file `classical' and
another version of the file `blues' have been added to `collection'.
Note: When you update an archive, tar does not overwrite old
archive members when it stores newer versions of a file. This is
because archive members appear in an archive in the order in which they
are stored, and some archive devices do not allow writing in the middle
of an archive.
@UNREVISED
Rather than adding individual files onto the end of an archive,
it may be more convenient to add archives themselves onto the end
of an archive. While it may seem intuitive to use cat, the
utility for adding files together, for this purpose, archives created
by tar incorporate an end of file marker which must be removed
if the concatenated archives are to be read properly as one archive.
@FIXME-xref{Ignore zeros}. To add archives to the end of another
archive, therefore, you should use the `--concatenate' (`-A') operation.
In earlier examples you created an archive file, `music', in your home directory. You have, however, since changed the contents of the `practice' directory which was stored in that archive. `collection', the archive file in the `practice' directory, has recently been updated, and contains a current version of the files in `practice'. Rather than update the contents of `music', let's add `collection' to it.
tar, and specify the operation to add archives to the
end of another archive---`--concatenate' (`-A').
% cd .. % tar --concatenate --file=music practice/collection
Rather than list the new contents of `music', let's extract all the files and see what happens.
To concatenate archive files, use the `--concatenate' (`-A') option.
This operation adds other archives to the end of an archive. While
it may seem intuitive to concatenate archives using cat,
the utility for adding files together, archive files which have
been "catted" together cannot be read properly by tar.
Archive files incorporate an end of file marker--if archives are
concatenated using cat, this marker will appear before the
end of the new archive. This will interfere with operations on that
archive. @FIXME-xref{ignore-zeros}. In earlier examples, you stored
the `~/practice' directory in an archive file, `~/music'.
If you have been following the examples, you have since changed
the contents of the `~/practice' directory. There is a current
version of the files in the `practice' directory, however, stored
in the archive file `~/practice/collection'.
To store current versions of the files in `practice' in the archive file `music', you can use `--concatenate' (`-A') to add the archive file `~/practice/collection' to `music'. First, make sure you are in your home directory (`cd ~'). Then:
tar, and specify the `--concatenate' (`-A') operation.
% cd ~ % tar --concatenate --file=music practice/collection
If you now list the contents of the `music', you see it now contains the archive members of `practice/collection':
%tar --list --file=music blues folk jazz rock blues practice/blues practice/folk practice/jazz practice/rock practice/blues practice/classical
@UNREVISED
You can delete members from an archive using `--delete'.
Specify the name of the archive with `--file=archive-name' (`-f archive-name'). List the member
names of the members to be deleted. (If you list no member names,
then nothing will be deleted.) The `--verbose' (`-v') option will cause
tar to print the names of the members as they are deleted.
As with `--extract' (`-x'), it is important that you give the exact
member names when using `tar --delete'. Use `--list' (`-t') to find
out the exact member names in an archive. See section How to List Archives.
The `--delete' option only works with archives stored on disk.
You cannot delete members from an archive stored on a tape.
In some instances, it may be advantageous to remove some files from an
archive stored on disk (it is never advantageous to delete files from
an archive stored on tape--the linear nature of tape storage makes
this action likely to scramble the archive). You can use the
`--delete' operation to remove files from an archive. The names
of files to be removed must be specified to tar as file name
arguments. All versions of the named file are removed from the
archive. Execution of the `--delete' operation can be very slow.
To delete all versions of the file `blues' from the archive `collection' in the `practice' directory, make sure you are in that directory, and then,
tar and specify the operation to delete files from an
archive (`--delete')
% tar --list --file=collection blues folk jazz % tar --delete --file=collection blues % tar --list --file=collection folk jazz %
In some instances, you may want to remove some files from an archive stored on disk
Caution: you should never delete files from an archive stored on tape--because of the linear nature of tape storage, doing this is likely to scramble the archive.
To remove archive members from an archive, use the `--delete' operation. You must specify the names of files to be removed as file name arguments. All versions of the named file are removed from the archive.
Execution of the `--delete' operation can be very slow.
To delete all versions of the file `blues' from the archive `collection' in the `practice' directory, make sure you are in that directory, and then:
tar and specify the `--delete' operation (`--delete').
% tar --list --file=collection blues folk jazz % tar --delete --file=collection blues % tar --list --file=collection folk jazz %