* Options:: How to change the way @code{tar} behaves.
* Problems:: Common problems with @code{tar}.
@end menu
-
-@node Tutorial, Wizardry, Invoking @code{tar}, Top
-@chapter Getting Started With @code{tar}
+@chapter Tutorial Introduction to @code{tar}
This chapter guides you through some basic examples of @code{tar}
operations. If you already know how to use some other version of
* Deleting Files:: Deleting Files From an Archive
@end menu
-@node Creating Archives, Listing Archive Contents, Tutorial, Tutorial
+@section What @code{tar} Does
+
+The @code{tar} program is used to create and manipulate @code{tar}
+archives. An @dfn{archive} is a single file which contains within it
+the contents of many files. In addition, the archive identifies the
+names of the files, their owner, and so forth.
+
+You can use @code{tar} archives in many ways. Initially, @code{tar}
+archives were used to store files conveniently on magnetic tape. The
+name @samp{tar} comes from this use; it stands for Tape ARchiver.
+Often, @code{tar} archives are used to store related files for
+convenient file transfer over a network. For example, the GNU Project
+distributes its software bundled into @code{tar} archives, so that all
+the files relating to a particular program (or set of related programs)
+can be transferred as a single unit.
+
+The files inside an archive are called @dfn{members}. Within this
+manual, we use the term @dfn{file} to refer only to files accessible in
+the normal ways (by @code{ls}, @code{cat}, and so forth), and the term
+@dfn{members} to refer only to the members of an archive. Similarly, a
+@dfn{file name} is the name of a file, as it resides in the filesystem,
+and a @dfn{member name} is the name of an archive member within the
+archive.
+
+The @code{tar} program provides the ability to create @code{tar}
+archives, as well as for various other kinds of manipulation. The term
+@dfn{extraction} is used to refer to the process of copying an archive
+member into a file in the filesystem. One might speak of extracting a
+single member. Extracting all the members of an archive is often called
+extracting the archive. Often the term @dfn{unpack} is used to refer to
+the extraction of many or all the members of an archive.
+
+Conventionally, @code{tar} archives are given names ending with
+@samp{.tar}. This is not necessary for @code{tar} to operate properly,
+but this manual follows the convention in order to get the reader used
+to seeing it.
+
+Occasionally archive members are referred to as files. For people
+familiar with the operation of @code{tar}, this causes no difficulty.
+However, this manual consistently uses the terminology above in
+referring to files and archive members, to make it easier to learn how
+to use @code{tar}.
+
@section Creating Archives
To create a new archive, use @samp{tar --create}. You should generally
use the @samp{--file} option to specify the name the tar archive will
-have. Then specify the names of the files you wish to place in the
-archive. For example, to place the files @file{foo}, @file{bar}, and
-@file{baz} into an archive named @file{my-archive}, use the following
-command:
+have. Then specify the names of the files you wish to place in the new
+archive. For example, to place the files @file{apple}, @file{angst},
+and @file{asparagus} into an archive named @file{afiles.tar}, use the
+following command:
@example
-tar --create --file=my-archive foo bar baz
+tar --create --file=afiles.tar apple angst asparagus
@end example
The order of the arguments is not important. You could also say:
@example
-tar foo --create --file=my-archive bar baz
+tar apple --create angst --file=afiles.tar asparagus
@end example
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 @samp{--file} option, then @code{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:
-
-@example
-tar: can't open /dev/rmt8 : No such device or address
-tar: can't open /dev/rsmt0 : I/O error
-@end example
-
-If you get an error like this, mentioning a file you didn't specify
-(@file{/dev/rmt8} or @file{/dev/rsmt0} in the examples above), then @code{tar}
-is using a default value for @samp{--file}. You should generally specify a
-@samp{--file} argument whenever you use @code{tar}, rather than relying
-on a default.
-
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:
@example
-tar --create --file=my-empty-archive
+tar --create --file=empty-archive.tar
@end example
Whenever you use @samp{tar --create}, @code{tar} will erase the current
to an existing archive, you need to use a different option.
@xref{Adding to Archives} for information on how to do this.
-The names of the members of an archive are called @dfn{member names}.
When @samp{tar --create} creates an archive, the member names of the
members of the archive are exactly the same as the file names as you
typed them in the @code{tar} command. So, the member names of
-@file{my-archive} (as created by the first example above) are
-@file{foo}, @file{bar}, and @file{baz}. However, suppose the archive
-were created with this command instead:
+@file{afiles} (as created by the first example above) are @file{apple},
+@file{angst}, and @file{asparagus}. However, suppose an archive were
+created with this command:
@example
-tar --create --file=my-new-archive ./foo bar ./baz
+tar --create --file=bfiles.tar ./balloons baboon ./bodacious
@end example
-Then, the same three files would get placed in the archive (because
-@file{./} is a synonym for the current directory), but their member
-names would now be @file{./foo}, @file{bar}, and @file{./baz}.
+Then, the three files @file{balloons}, @file{baboon}, and
+@file{bodacious} would get placed in the archive (because @file{./} is a
+synonym for the current directory), but their member names would be
+@file{./balloons}, @file{baboon}, and @file{./bodacious}.
If you want to see the progress of tar as it writes files into the
archive, you can use the @samp{--verbose} option.
the operation of tar is more complicated. @xref{Tar and Directories},
the last section of this tutorial, for more information.
+If you don't specify the @samp{--file} option, then @code{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:
+
+@example
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
+@end example
+
+If you get an error like this, mentioning a file you didn't specify
+(@file{/dev/rmt8} or @file{/dev/rsmt0} in the examples above), then @code{tar}
+is using a default value for @samp{--file}. You should generally specify a
+@samp{--file} argument whenever you use @code{tar}, rather than relying
+on a default.
+
@section Listing Archives
Use @samp{tar --list} to print the names of members stored in an
archive. Use a @samp{--file} option just as with @samp{tar --create} to
specify the name of the archive. For example, the archive
-@file{my-archive} created in the last section could be examined with the
-command @samp{tar --list --file=my-archive}. The output of tar would
+@file{afiles.tar} created in the last section could be examined with the
+command @samp{tar --list --file=afiles.tar}. The output of tar would
then be:
@example
-foo
-bar
-baz
+apple
+angst
+asparagus
@end example
-The archive @file{my-new-archive} would list as follows:
+The archive @file{bfiles.tar} would list as follows:
@example
-./foo
-bar
-./baz
+./baloons
+baboon
+./bodacious
@end example
-Note that, despite the identical contents of the two archives' members,
-the member names are different. (Of course, @samp{tar --list
---file=my-empty-archive} would produce no output.)
+(Of course, @samp{tar --list --file=empty-archive.tar} would produce no
+output.)
If you use the @samp{--verbose} option with @samp{tar --list}, then tar
will print out a listing reminiscent of @samp{ls -l}, showing owner,
You can also specify member names when using @samp{tar --list}. In this
case, tar will only list the names of members you identify. For
-example, @samp{tar --list --file=my-archive foo} would only print
-@samp{foo}. It is essential when specifying member names to tar that
+example, @samp{tar --list --file=afiles.tar apple} would only print
+@samp{apple}. It is essential when specifying member names to tar that
you give the exact member names. For example, @samp{tar --list
---file=my-new-archive foo} would produce no output, because there is no
-member named @file{foo}, only one named @file{./foo}. While the file
-names @file{foo} and @file{./foo} name the same file, member names are
-compared using a simplistic name comparison, in which an exact match is
-necessary.
+--file=bfiles baloons} would produce no output, because there is no
+member named @file{baloons}, only one named @file{./baloons}. While the
+file names @file{baloons} and @file{./baloons} name the same file,
+member names are compared using a simplistic name comparison, in which
+an exact match is necessary.
-@section Extracting Files from an Archive
+@section Extracting Members from an Archive
-In order to extract files from an archive, use @samp{tar --extract}.
+In order to extract members from an archive, use @samp{tar --extract}.
Specify the name of the archive with @samp{--file}. To extract specific
archive members, give their member names as arguments. It essential to
-give their exact member name, as printed by @samp{tar --list}.
+give their exact member name, as printed by @samp{tar --list}. 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, @samp{tar --extract --file=my-archive foo} would create a file
-@file{foo} in the current directory with the contents of the archive
-member @file{foo}. It would remove any file named @file{foo} already
-present in the directory, but it would not change the archive in any
-way.
+tutorial, @samp{tar --extract --file=afiles.tar apple} would create a
+file @file{apple} in the current directory with the contents of the
+archive member @file{apple}. It would remove any file named
+@file{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. @samp{tar
---extract --file=my-new-archive foo} will fail, because there is no
-member named @file{foo}. To extract the member named @file{./foo} you
-would need to specify @samp{tar --extract --file=my-new-archive ./foo}.
-To find the exact member names of the members of an archive, use
-@samp{tar --list}. @xref{Listing Archives}.
+--extract --file=bfiles.tar baloons} will fail, because there is no
+member named @file{baloons}. To extract the member named
+@file{./baloons} you would need to specify @samp{tar --extract
+--file=bfiles.tar ./baloons}. To find the exact member names of the
+members of an archive, use @samp{tar --list} (@pxref{Listing
+Archives}).
If you do not list any archive member names, then @samp{tar --extract}
will extract all the members of the archive.
@section Adding Files to Existing Archives
If you want to add files to an existing archive, then don't use
-@samp{tar --create}. That will erase an archive and create a new one in
-its place. Instead, use @samp{tar --add-file}. The command @samp{tar
---add-file --file=my-archive qux} would add the file @file{qux} to the
-existing archive @file{my-archive}. It is essential that the archive
-exist already in order to use @samp{tar --add-file}.
+@samp{tar --create}. That will erase the archive and create a new one
+in its place. Instead, use @samp{tar --append}. The command @samp{tar
+--append --file=afiles.tar arbalest} would add the file @file{arbalest}
+to the existing archive @file{afiles.tar}. The archive must already
+exist in order to use @samp{tar --append}.
As with @samp{tar --create}, the member names of the newly added files
will be the exact same as their names given on the command line. The
@samp{--verbose} 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 @samp{tar --add-file} with the
+If you add a file to an archive using @samp{tar --append} 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. @xref{Multiple Members with the Same Name}. If you want to
replace an archive member, use @samp{tar --delete} first, and then use
-@samp{tar --add-file}.
+@samp{tar --append}.
-@section Deleting Files from Archives
+@section Deleting Members from Archives
-You can delete files from an archive using @samp{tar --delete}. Specify
-the name of the archive with @samp{--file}. List the member names of
-the files to be deleted. If you list no member names, then nothing will
-be deleted. The @samp{--verbose} option will cause @code{tar} to print
-the names of the members as they are deleted. As with @samp{tar
---extract}, it is important that you give the exact member names when
-using @samp{tar --delete}. Use @samp{tar --list} to find out the exact
-member names in an archive (@pxref{Listing Archives}).
+You can delete members from an archive using @samp{tar --delete}.
+Specify the name of the archive with @samp{--file}. List the member
+names of the members to be deleted. (If you list no member names, then
+nothing will be deleted.) The @samp{--verbose} option will cause
+@code{tar} to print the names of the members as they are deleted. As
+with @samp{tar --extract}, it is important that you give the exact
+member names when using @samp{tar --delete}. Use @samp{tar --list} to
+find out the exact member names in an archive (@pxref{Listing
+Archives}).
The @samp{tar --delete} command only works with archives stored on disk.
-Archives stored on a tape drive cannot be deleted from.
+You cannot delete members from an archive stored on a tape.
@section Directories
-When the names of files or member names specify directories, the
-operation of @code{tar} is more complex. Generally, when a directory is
-named, @code{tar} also operates on all the contents of the directory,
+When the names of files or members specify directories, the operation of
+@code{tar} is more complex. Generally, when a directory is named,
+@code{tar} also operates on all the contents of the directory,
recursively. Thus, to @code{tar}, the file name @file{/} names the
-entire file system.
+entire file system.
To archive the entire contents of a directory, use @samp{tar --create}
-(or @samp{tar --add-file}) as usual, and specify the name of the
+(or @samp{tar --append}) as usual, and specify the name of the
directory. For example, to archive all the contents of the current
directory, use @samp{tar --create --file=@var{archive-name} .}. Doing
this will give the archive members names starting with @samp{./}. To
--create --file=@var{archive-name} foodir}. In this case, the member
names will all start with @samp{foodir/}.
-If you give @code{tar} a command such as @samp{tar --create --file=foo
-.}, it will report @samp{tar: foo is the archive; not dumped}. This
-happens because the archive @file{foo} is created before putting any
-files into it. Then, when @code{tar} attempts to add all the files in
-the directory @file{.} to the archive, it notices that the file
-@file{foo} is the same as the archive, and skips it. (It makes no sense
-to put an archive into itself.) GNU @code{tar} will continue in this
-case, and create the archive as normal, except for the exclusion of that
-one file. Other versions of @code{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.
+If you give @code{tar} a command such as @samp{tar --create
+--file=foo.tar .}, it will report @samp{tar: foo.tar is the archive; not
+dumped}. This happens because the archive @file{foo.tar} is created
+before putting any files into it. Then, when @code{tar} attempts to add
+all the files in the directory @file{.} to the archive, it notices that
+the file @file{foo.tar} is the same as the archive, and skips it. (It
+makes no sense to put an archive into itself.) GNU @code{tar} will
+continue in this case, and create the archive as normal, except for the
+exclusion of that one file. Other versions of @code{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, @code{tar} extracts all the archive
extract all the contents of the archive, but only those members whose
member names begin with @samp{./}.
+@section Shorthand names
+
+Most of the options to @code{tar} come in both long forms and short
+forms. The options described in this tutorial have the following
+abbreviations (except @samp{--delete}, which has no shorthand form):
+
+@table @samp
+@item --create
+@samp{-c}
+@item --list
+@samp{-t}
+@item --extract
+@samp{-x}
+@item --append
+@samp{-r}
+@item --verbose
+@samp{-v}
+@item --file=@var{archive-name}
+@samp{-f @var{archive-name}}
+@end table
+
+These options make typing long @code{tar} commands easier. For example,
+instead of typing
+@example
+tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus
+@end example
+you can type
+@example
+tar -c -f /tmp/afiles.tar -v apple angst asparagus
+@end example
+
+For more information on option syntax, @ref{Invoking @code{tar}}. In
+the remainder of this manual, short forms and long forms are given
+together when an option is discussed.
-@node Invoking @code{tar}, Tutorial, Introduction, Top
-@chapter How To Invoke @code{tar}
+@chapter Invoking @code{tar}
The usual way to invoke tar is
@example
-@code{tar} @var{options}... [@var{file-names}...]
+@code{tar} @var{options}... [@var{file-or-member-names}...]
@end example
-All the options start with @samp{-}. The arguments which do not start
-with @samp{-} are taken to be file-name arguments. (But
-@xref{Argument Form}.) You can actually type in arguments in any
-order. In this manual the options always precede the file-name
-arguments, to make examples easier to understand.
+All the options start with @samp{-}. You can actually type in arguments
+in any order, but in this manual the options always precede the other
+arguments, to make examples easier to understand.
@menu
* Option Form:: The Forms of Arguments
for @code{tar} Commands
@end menu
-@node Option Form, Old Syntax for Commands, Argument Functions, Invoking @code{tar}
@section The Forms of Arguments
Most options of @code{tar} have a single letter form (a single letter
no other option which begins with @samp{cre}.
Some options require an additional argument. Single letter options
-which require arguments use the immediately following argument. (This
-is an exception to the rule that @code{tar} arguments which are not
-options are file-name arguments.) Mnemonic options are separated from
-their arguments by an @samp{=} sign. For example, to create an an
-archive file named @file{george}, use either @samp{tar --create
---file=george} or @samp{tar --create -f george}. Both
-@samp{--file=@var{archive-name}} and @samp{-f @var{archive-name}}
-denote the option to give the archive a non-default name, which in the
-example is @samp{george}.
+which require arguments use the immediately following argument.
+Mnemonic options are separated from their arguments by an @samp{=}
+sign. For example, to create an an archive file named
+@file{george.tar}, use either @samp{tar --create --file=george.tar} or
+@samp{tar --create -f george.tar}. Both
+@samp{--file=@var{archive-name}} and @samp{-f @var{archive-name}} denote
+the option to give the archive a non-default name, which in the example
+is @file{george.tar}.
You can mix single letter and mnemonic forms in the same command. You
could type the above example as @samp{tar -c --file=george} or
it needs to change to a directory named @samp{--file=george}, and
wouldn't interpret @samp{--file-george} as an option at all!
-@node Argument Functions, Argument Form, Invoking @code{tar}, Invoking @code{tar}
@section The Functions of Arguments
You must give exactly one option from the following list to tar. This
-option specifies the basic operation for tar to perform.
+option specifies the basic operation for @code{tar} to perform.
-@itemize
-@item
-Add files to an existing archive (@samp{--add-file}, @samp{--append} or
-@samp{-r})
+@table samp
+@item --help
+Print a summary of the options to @code{tar} and do nothing else
-@item
-Compare files in an archive with files in the file system
-(@samp{--compare}, @samp{--diff} or @samp{-d})
+@item --create
+@item -c
+Create a new archive
-@item
-Add archives to another archive (@samp{--add-archive}, @samp{--catenate}
-or @samp{-A})
-@c was --concatenate. -ringo
+@item --catenate
+@item --concatenate
+@item -A
+Add the contents of one or more archives to another archive
-@item
-Create a new archive (@samp{--create} or @samp{-c})
+@item --append
+@item -a
+Add files to an existing archive
-@item
-Delete files from an archive (@samp{--delete})
+@item --list
+@item -t
+List the members in an archive
-@item
-Extract files from an archive (@samp{--extract}, @samp{--get} or @samp{-x})
+@item --delete
+Delete members from an archive
-@item
-List the files in an archive (@samp{--list} or @samp{-t})
+@item --extract
+@item --get
+@item -x
+Extract members from an archive
-@item
+@item --compare
+@item --diff
+@item -d
+Compare members in an archive with files in the file system
+
+@item --update
+@item -u
Update an archive by appending newer versions of already stored files
-(@samp{--update} or @samp{-u})
@end itemize
-@xref{Reading and Writing}, for more information about these
-operations.
-
The remaining options to @code{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 file-name arguments. For --add-file and
---create these arguments specify the names of files (which must
-already exist) to place in the archive. For the remaining operation
-types, the file-name 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. When naming
+The remaining arguments are interpreted either as file names or as
+member names, depending on the basic operation @code{tar} is
+performing. For @samp{--append} and @samp{--create} 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 @code{tar --list}. When naming
files, the normal file name rules apply.
-If you don't use any file-name arguments, @samp{--add-file},
-@samp{--update} and @samp{--delete} will do nothing. Naturally,
-@samp{--create} will make an empty archive if given no file-name
-arguments. The other operations of @code{tar} will act on defaults.
+If you don't use any additional arguments, @samp{--append},
+@samp{--catenate}, and @samp{--delete} will do nothing. Naturally,
+@samp{--create} will make an empty archive if given no files to add.
+The other operations of @code{tar} (@samp{--list}, @samp{--extract},
+@samp{--compare}, and @samp{--update}) will act on the entire contents
+of the archive.
-Anytime you use a file-name argument to specify a directory file,
-@code{tar} acts recursively on all the files and directories beneath
-that directory.
+If you give the name of a directory as either a file name or a member
+name, then @code{tar} acts recursively on all the files and directories
+beneath that directory. For example, the name @file{/} identifies all
+the files in the filesystem to @code{tar}.
-@node Old Syntax for Commands, , Argument Form, Invoking @code{tar}
@section An Old, but Still Supported, Syntax for @code{tar} Commands
For historical reasons, GNU @code{tar} also accepts a syntax for
argument. The modern syntax---@samp{tar -c -v -b 20 -f
/dev/rmt0}---is clearer.
+@chapter Specifying Names to @code{tar}
+
+When specifying the names of files or members to @code{tar}, it by
+default takes the names of the files from the command line. There are
+other ways, however, to specify file or member names, or to modify the
+manner in which @code{tar} selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+
+@section Reading Names from a File
+
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+@samp{--files-from=@var{file-name-list}} (@samp{-T
+@var{file-name-list}}) option to @code{tar}. Give the name of the file
+which contains the list as the argument to @samp{--files-from}. The
+file names should be separated by newlines in the list.
+
+If you want to specify names that might contain newlines, use the
+@samp{--null} option. Then, the filenames should be separated by NUL
+characters (ASCII 000) instead of newlines. In addition, the
+@samp{--null} option turns off the @samp{-C} option (@pxref{Changing
+Directory}).
+
+@section Excluding Some Files
+
+The @samp{--exclude=@var{pattern}} option will prevent any file or
+member which matches the regular expression @var{pattern} from being
+operated on. For example, if you want to create an archive with all the
+contents of @file{/tmp} except the file @file{/tmp/foo}, you can use the
+command @samp{tar --create --file=arch.tar --exclude=foo}.
+
+If there are many files you want to exclude, you can use the
+@samp{--exclude-from=@var{exclude-list}} (@samp{-X @var{exclude-list}})
+option. This works just like the
+@samp{--files-from=@var{file-name-list}} option: specify the name of a
+file as @var{exclude-list} which contains the list of patterns you want
+to exclude.
+
+@xref{Regular Expressions} for more information on the syntax and
+meaning of regular expressions.
+
+@section Operating Only on New Files
+
+The @samp{--newer=@var{date}} (@samp{--after-date=@var{date}} or
+@samp{-N @var{date}}) limits @code{tar} to only operating on files which
+have been modified after the date specified. (For more information on
+how to specify a date, @xref{Date Formats}.) A file is considered to
+have changed if the contents have been modified, or if the owner,
+permissions, and so forth, have been changed.
+
+If you only want @code{tar} make the date comparison on the basis of the
+actual contents of the file's modification, then use the
+@samp{--newer-mtime=@var{date}} option.
+
+You should not depend on this option for making incremental dumps. To
+learn how to use @code{tar} to make backups, @ref{Making Backups}.
+
+XXXX MIB XXXX
+
+
+
@node Wizardry, Archive Structure, Tutorial, Top
@chapter Wizardry
projects / chaz / tar / commitdiff
