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".
FIXME: xref 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):
`--create'
`-c'
`--list'
`-t'
`--extract'
`-x'
`--append'
`-r'
`--verbose'
`-v'
`--file=ARCHIVE-NAME'
`-f ARCHIVE-NAME'
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,
FIXME: ref Invoking tar
. In discussions in the text, when we present some mnemonic option,
we also give the corresponding short option within parentheses.
* Menu:
* How to Create Archives::
* How to List Archives::
* How to Extract Members from an Archive::
* How to Add Files to Existing Archives::
* How to Delete Members from Archives::
File: tar.info, Node: How to Create Archives, Next: How to List Archives, Prev: Tutorial, Up: Tutorial
How to Create Archives
======================
*(This message will disappear, once this node revised.)*
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.
FIXME: xref Creating
, 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
This order is harder to understand however. In this manual, we will
list the arguments in a reasonable order to make the commands easier to
understand, but you can type them in any order you wish.
If you don't specify the names of any files to put in the archive,
then `tar' will create an empty archive. So, the following command
will create an archive with nothing in it:
tar --create --file=empty-archive.tar
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.
FIXME: xref Adding to Archives, 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.
FIXME: xref Tar and Directories,
FIXME: the last section of this tutorial, 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.
FIXME: xref Creating Example
, for more information about the `--create' (`-c') option.
* Menu:
* Creating Archives of Files bis::
* Using tar in Verbose Mode bis::
* How to Archive Directories::
* Creating an Archive of a Subdirectory bis::
* Compare bis::
* Using Compare from the Superior Directory bis::
File: tar.info, Node: Creating Archives of Files bis, Next: Using tar in Verbose Mode bis, Prev: How to Create Archives, Up: How to Create Archives
Creating Archives of Files
--------------------------
*(This message will disappear, once this node revised.)*
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 `records'. 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,
* Create a new archive by giving `--create' (`-c') to `tar'.
* Explicitly name the archive file being
created--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME'). If you don't
use this option `tar' will write the archive to the default
storage device, which varies from system to system.
* Specify which files to put into the archive. If you don't specify
any FILE NAME arguments, `tar' will archive everything in the
working directory.
Type:
% tar --create --file=records 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 records
%
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 `records'. 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,
* Create a new archive by giving the `--create' (`-c') option to
`tar'.
* Explicitly name the archive file being
created--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME'). If you don't
use this option `tar' will write the archive to the default
storage device, which varies from system to system.
FIXME: this syntax may change. OK now--check before printing
`tar' interprets archive file names relative to the working
directory. Make sure you have write access to the working
directory before using `tar'.
* Specify which files to put into the archive (`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=records 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 records
%
File: tar.info, Node: Using tar in Verbose Mode bis, Next: How to Archive Directories, Prev: Creating Archives of Files bis, Up: How to Create Archives
Using `tar' in Verbose Mode
---------------------------
*(This message will disappear, once this node revised.)*
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=records --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=records --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.
File: tar.info, Node: How to Archive Directories, Next: Creating an Archive of a Subdirectory bis, Prev: Using tar in Verbose Mode bis, Up: How to Create Archives
How to Archive Directories
--------------------------
*(This message will disappear, once this node revised.)*
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
`./'.
* Menu:
* Creating an Archive of a Subdirectory bis::
File: tar.info, Node: Creating an Archive of a Subdirectory bis, Next: Compare bis, Prev: How to Archive Directories, Up: How to Create Archives
Creating an Archive from the Superior Directory
-----------------------------------------------
*(This message will disappear, once this node revised.)*
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/records
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.
FIXME: xref absolute-names
(Note also that `records', 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
`records' 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.
FIXME: add an xref to --absolute-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/records
Note that `~/practice/records', another archive file, has itself
been archived. `tar' will accept any file as a file to be archived,
even an archive file.
FIXME: symbolic links and changing directories are now in main body,
FIXME: not in tutorial.
File: tar.info, Node: Compare bis, Next: Using Compare from the Superior Directory bis, Prev: Creating an Archive of a Subdirectory bis, Up: How to Create Archives
Comparing Files in an Archive with Files in the File System
