@c <<< @code{tar} is always lower case, in bold. >>>
@c <<< it's "operations of tar", "options to tar" also, it's " @samp{tar
-+foo}" or "the @samp{+foo} operation". MIB doesn't like using
+--foo}" or "the @samp{--foo} operation". MIB doesn't like using
operations and options as separate concepts. I disagree --- would be a
mess to explain otherwise
@subtitle DRAFT
@c subtitle insert month here when ready
-@author Amy Gorin and Jay Fenlason
+@author Amy Gorin, Michael I. Bushnell, and Jay Fenlason
@c <<<best to have hack read this over and see if anything is left he
@c wrote. I don't think so. -ringo>>>>
@chapter @code{tar}: The GNU Tape Archiver
You can use @code{tar} to create an @dfn{archive}---a single file
-which contains other file's contents as well as a listing of those
+which contains other files' contents as well as a listing of those
files' characteristics. You can also use @code{tar} to read, add to,
or manipulate already existing archives. Because an archive created
by @code{tar} is capable of preserving file information and directory
backups, as well as for transferring groups of files between disks and
over networks.
-Despite the utility's name, which comes from the words @samp{T(ape)}
-@samp{AR(chiver)}, @code{tar}'s output can be directed to any
-available device. For instance, @code{tar} archives can be stored in
-a file or sent to another program via a pipe.
+The name @code{tar} comes from the words ``Tape ARchiver'', but
+@code{tar} can actually process archives wherever they are stored; on
+tapes and disk files, for example. In addition, tar can read archives
+from standard input or write them to standard output. (This is often
+useful if redirected another program with a pipe.)
@c <<< this menu will conflict with menu above in info mode. -ringo
@menu
* Options:: How to change the way @code{tar} behaves.
* Problems:: Common problems with @code{tar}.
@end menu
-
-@node Invoking @code{tar}, Tutorial, Introduction, Top
-@chapter How To Invoke @code{tar}
-
-You can use @code{tar} to store files in an archive, to extract them
-from an archive, and to do other types of archive manipulation. The
-primary argument to @code{tar}, which is called the @dfn{operation},
-specifies which action to take. The other arguments to @code{tar} are
-either @dfn{options}, which change the way @code{tar} performs an
-operation, or @dfn{file-names}, which specify the files @code{tar} is
-to act on. The typical @code{tar} command line syntax is:
-
-@example
-@code{tar} @var{operation} [@var{options}...] [@var{file-names}...]
-@end example
-
-Note: You can actually type in arguments in any order. In this manual
-the operation is always first, the options second and the file-name
-arguments last, to make examples easier to understand.
-
-@menu
-* Argument Functions:: The Functions of Arguments
-* Argument Form:: The Forms of Arguments
-* Old Syntax for Commands:: An Old, but Still Supported, Syntax
- for @code{tar} Commands
-@end menu
-
-@node Argument Functions, Argument Form, Invoking @code{tar}, Invoking @code{tar}
-@section The Functions of Arguments
-
-The primary argument to @code{tar} is the @dfn{operation}, which
-specifies what @code{tar} does. @code{tar} can be used to:
-
-@itemize
-@item
-Add files to an existing archive (@samp{+add-file}, @samp+{append} or
-@samp{-r})
-
-@item
-Compare files in an archive with files in the file system
-(@samp{+compare}, @samp{+diff} or @samp{-d})
-@c !!! is diff still working?? --- yes -ringo
-
-@item
-Add archives to another archive (@samp{+add-archive}, @samp{+catenate}
-or @samp{-A})
-@c was +concatenate. -ringo
-
-@item
-Create an archive (@samp{+create} or @samp{-c})
-
-@item
-Delete files from an archive (@samp{+delete})
-@c -D should have been removed -ringo
-
-@item
-Extract files from an archive (@samp{+extract}, @samp{+get} or @samp{-x})
-
-@item
-List the files in an archive (@samp{+list} or @samp{-t})
-
-@item
-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.
-
-@dfn{Option} arguments 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. All options are optional.
-
-@dfn{File-name} arguments specify which files (including directory
-files) to archive, extract, delete or otherwise operate on.
-
-If you don't use any file-name arguments, @samp{+add-file},
-@samp{+update} and @samp{+delete} will do nothing. The other
-operations of @code{tar} will act on defaults.
-
-When you use a file-name argument to specify a directory file,
-@code{tar} acts on all the files in that directory, including
-sub-directories.
-
-@node Argument Form, Old Syntax for Commands, Argument Functions, Invoking @code{tar}
-@section The Forms of Arguments
-
-Most operations of @code{tar} have a single letter form (a single
-letter preceded by a @samp{-}), and at least one mnemonic form (a
-word or abbreviation preceded by a @samp{+}). The forms are
-identical in function. For example, you can use either @samp{tar -t}
-or @samp{tar +list} to list the contents of an archive
-
-Options, like operations, have both single letter and mnemonic forms.
-Options, however, may also incorporate an argument. Single letter
-options are separated from their arguments by a space. 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}.
-
-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
-@samp{tar +create -f george}. However, @code{tar} operations and
-options are case sensitive. You would not type the above example as
-@samp{tar -C +file=george}, because @samp{-C} is an option that causes
-@code{tar} to change directories, not an operation that creates an
-archive.
-
-File-name arguments are the names of files (including directories).
-These names can be specified on the command line or read from a text
-file in the file system (using the @samp{+files-from} option). Files
-stored in an archive are called @dfn{archive members}. The operations
-@samp{+delete}, @samp{+extract}, @samp{+list}, @samp{+compare} and
-@samp{+update} take the names of archive members as file-name
-arguments. The other operations take the names of files in the file
-system.
-
-@code{tar} interprets relative file names as being relative to the
-working directory. @code{tar} will make all file names relative (by
-removing leading @samp{/}s when archiving or restoring files), unless
-you specify otherwise (using the @samp{+absolute-paths} option).
-@xref{File Name Interpretation}, for more information about
-@samp{+absolute-paths}.
-@c >>> yet another node name that is probably wrong.
-
-@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
-commands which splits options that include arguments into two parts.
-That syntax is of the form:
-
-@example
-@code{tar} @var{operation}[@var{option-letters}...] [@var{option-arguments}...] [@var{file-names}...]@refill
-@end example
-
-@noindent
-where arguments to the options appear in the same order as the letters
-to which they correspond, and the operation and all the option letters
-appear as a single argument, without separating spaces.
-
-This command syntax is useful because it lets you type the single
-letter forms of the operation and options as a single argument to
-@code{tar}, without writing preceding @samp{-}s or inserting spaces
-between letters. @samp{tar cv} or @samp{tar -cv} are equivalent to
-@samp{tar -c -v}.
-
-This old style syntax makes it difficult to match option letters with
-their corresponding arguments, and is often confusing. In the command
-@samp{tar cvbf 20 /dev/rmt0}, for example, @samp{20} is the argument
-for @samp{-b}, @samp{/dev/rmt0} is the argument for @samp{-f}, and
-@samp{-v} does not have a corresponding argument. The modern
-syntax---@samp{tar -c -v -b 20 -f /dev/rmt0}---is clearer.
-
-@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. In the examples, the lines you should type are preceded
-by a @samp{%}, 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.
+operations. If you already know how to use some other version of
+@code{tar}, then you probably don't need to read this chapter. This
+chapter omits complicated details about many of the ways @code{tar}
+works. See later chapters for full information.
@menu
* Creating Archives:: Creating Archives
* Deleting Files:: Deleting Files From an Archive
@end menu
-@node Creating Archives, Listing Archive Contents, Tutorial, Tutorial
-@section Creating Archives
-
-To create a new archive, use @code{tar +create} (or @code{tar -c}).
-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, @code{tar} will use default values.
-@xref{Creating Example}, for more information about the @samp{+create}
-operation.
-
-@menu
-* Creating Example:: Creating Archives of Files
-* Subdirectory:: Creating an Archive of a Subdirectory
-@end menu
-
-@node Creating Example, Subdirectory, Creating Archives, Creating Archives
-@subsection Creating Archives of Files
-
-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 @file{blues},
-@file{folk}, and @file{jazz}. The archive file is called
-@file{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 @file{practice} containing files called @file{blues},
-@file{folk} and @file{jazz}. To create the directory, type
-@samp{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:
-
-@example
-% cd practice
-@end example
+@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.
-@noindent
-@file{~/practice} is now your working directory.
+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}.
-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, @code{tar} will
-overwrite the old file and its contents will be lost.
+@section Creating Archives
-To list the names of files in the working directory, type:
+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 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
-% ls
+tar --create --file=afiles.tar apple angst asparagus
@end example
-The system responds:
+The order of the arguments is not important. You could also say:
@example
-blues folk jazz
-%
+tar apple --create angst --file=afiles.tar asparagus
@end example
-@noindent
-Then,
-@itemize @bullet
-@item
-Create a new archive (@samp{tar -c} or @samp{tar +create})
-
-@item
-Explicitly name the archive file being created (@samp{-f
-@var{archive-name}} or @samp{+file=@var{archive-name}}). If you don't
-use this option @code{tar} will write the archive to the default
-storage device, which varies from system to system.
-@c <<< this syntax may change. OK now---check before printing -ringo
-
-@code{tar} interprets archive file names relative to the working
-directory. Make sure you have write access to the working directory
-before using @code{tar}.
-
-@item
-Specify which files to put into the archive (@code{tar} interprets
-file names relative to the working directory). If you don't use any
-@var{file-name} arguments, @code{tar} will archive everything in the
-working directory.
-@end itemize
-
-@noindent
-Type:
-@example
-% tar +create +file=records blues folk jazz
-@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.
-@noindent
-If you now list the contents of the working directory (@samp{ls}), you
-will find the archive file listed as well as the files you saw
-previously.
+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
-% ls
-blues folk jazz records
-%
+tar --create --file=empty-archive.tar
@end example
-@menu
-* Listing Files:: Listing files in an archive
-* Verbose:: Using @code{tar} in Verbose Mode
-@end menu
-
-@node Listing Files, Verbose, Creating Example, Creating Example
-@subsubsection Listing files in an archive
+Whenever you use @samp{tar --create}, @code{tar} will erase the current
+contents of the file named by @samp{--file} if it exists. To add files
+to an existing archive, you need to use a different option.
+@xref{Adding to Archives} for information on how to do this.
-You can list the contents of an archive with another operation of
-@code{tar}---@samp{+list} or @samp{-l}. To list the contents of the
-archive you just created, type:
+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{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 +list +file=records
+tar --create --file=bfiles.tar ./balloons baboon ./bodacious
@end example
-@noindent
-@code{tar} will respond:
-
-@example
-blues folk jazz
-@end example
+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}.
-@xref{Listing Archive Contents}, for a more detailed tutorial of the
-@samp{+list} operation. @xref{Listing Contents}, for more information
-about the @samp{+list} operation.
+If you want to see the progress of tar as it writes files into the
+archive, you can use the @samp{--verbose} option.
-@node Verbose, , Listing Files, Creating Example
-@subsubsection Using @code{tar} in Verbose Mode
+If one of the files named to @samp{tar --create} is a directory, then
+the operation of tar is more complicated. @xref{Tar and Directories},
+the last section of this tutorial, for more information.
-If you include the @samp{+verbose} or @samp{-v} option on the command
-line, @code{tar} will list the files it is acting on as it is working.
-In verbose mode, the creation example above would appear as:
-@cindex Verbose mode example
-@findex -v (verbose mode example)
+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 +create +file=records +verbose blues folk jazz
-blues
-folk
-jazz
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
@end example
-@noindent
-The first line is the command typed in by the user. The remaining
-lines are generated by @code{tar}. In the following examples we
-usually use verbose mode, though it is almost never required.
-
-@node Subdirectory, Changing, Creating Example, Creating Archives
-@subsection Creating an Archive of a Subdirectory
+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.
-You can store a directory in an archive by using the directory name as
-a file-name argument to @code{tar}. When you specify a directory
-file, @code{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.
-@c <<< add an xref to +absolute-paths -ringo
+@section Listing Archives
-To archive a directory, first move to its superior directory. If you
-have been following the tutorial, you should type:
+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{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
-% cd ..
-%
+apple
+angst
+asparagus
@end example
-Once in the superior directory, specify the subdirectory using a
-file-name argument. To store the directory file @file{~/practice} in
-the archive file @file{music}, type:
+The archive @file{bfiles.tar} would list as follows:
@example
-% tar +create +verbose +file=music practice
+./baloons
+baboon
+./bodacious
@end example
-@noindent
-@code{tar} should respond:
+(Of course, @samp{tar --list --file=empty-archive.tar} would produce no
+output.)
-@example
-practice/
-practice/blues
-practice/folk
-practice/jazz
-practice/records
-@end example
-
-Note that @file{~/practice/records}, another archive file, has
-itself been archived. @code{tar} will accept any file as a file to be
-archived, even an archive file.
-
-@c >>> symbolic links and changing directories are now in main body, not in
-@c >>> tutorial. -ringo
-
-@node Extracting Files
-@section Extracting Files from an Archive
-
-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 @samp{+extract} or @samp{-x} operation.
-
-To extract specific files, use their names as file-name arguments. If
-you use a directory name as a file-name argument, @code{tar} extracts
-all the files (including subdirectories) in that directory. If you
-don't use any file-name arguments, @code{tar} extracts all the files
-in the archive.
+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,
+file size, and so forth.
-Note: @code{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, @code{tar}
-will @strong{overwrite} that file and its contents will be lost.
-@c <<<xref keep-old -ringo
+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=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=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.
-@node Extracting Specific Files, , ,
-@subsection Extracting Specific Files
+@section Extracting Members from an Archive
-To extract specific files, specify them using file-name arguments.
+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}. This
+will create a copy of the archive member, with a file name the same as
+its name in the archive.
-In an example above, you created the archive file
-@file{~/practice/records}, which contained the files @file{blues},
-@file{folk} and @file{jazz} in the @file{practice} directory. If, for
-some reason, you were to lose one of those text files (@samp{rm
-~/practice/blues}), you could extract it from the archive file.
+Keeping the example of the two archives created at the beginning of this
+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.
-First, change into the @file{practice} directory. Then,
+Remember that specifying the exact member name is important. @samp{tar
+--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}).
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{+extract} operation
-(@samp{+extract}, @samp{+get} or @samp{-x})
+If you do not list any archive member names, then @samp{tar --extract}
+will extract all the members of the archive.
-@item
-Specify the archive that the files will be extracted from
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
+If you give the @samp{--verbose} option, then @samp{tar --extract} will
+print the names of the archive members as it extracts them.
-@item
-Specify the files to extract, using file-name arguments (if you don't
-specify any files, @code{tar} extracts all the archive members)
-@end itemize
-
-@example
-% tar +extract +file=records blues
-@end example
-
-If you list the contents of the directory, you will see that
-@file{blues} is back:
-
-@example
-% ls
-folk
-jazz
-records
-blues
-@end example
-
-@node Extracting Directories, , ,
-@subsection Extracting Directories
-
-To extract a directory and all the files it contains, use the
-directory's name as a file-name argument in conjunction with @samp{tar
-+extract}. Remember---@code{tar} stores and extracts file names
-relative to the working directory.
+@section Adding Files to Existing Archives
-In a previous example you stored the directory @file{~/practice} in
-the archive file @file{~/music}. If you delete the contents of
-@file{practice}, you can restore them using @code{tar}.
+If you want to add files to an existing archive, then don't use
+@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 --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 --append}.
+
+@section Deleting Members from 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.
+You cannot delete members from an archive stored on a tape.
+
+@section Directories
+
+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.
+
+To archive the entire contents of a directory, use @samp{tar --create}
+(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
+archive the contents of a directory named @file{foodir}, use @samp{tar
+--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.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
+members whose names begin with the name of the directory. As usual,
+@code{tar} is not particularly clever about interpreting member names.
+The command @samp{tar --extract --file=@var{archive-name} .} will not
+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):
-First, change into the @file{practice} subdirectory (@samp{cd
-~/practice}). Then, remove all the files in @samp{~/practice}
-(@samp{rm *}). If you list the contents of the directory, you should
-now see that it is empty:
+@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
-%ls
-%
+tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus
@end example
-
-@noindent Let's try to restore the contents of @file{practice} by extracting
-them from the archive file @file{~/music}:
-
+you can type
@example
-tar +extract +file=~/music practice
+tar -c -f /tmp/afiles.tar -v apple angst asparagus
@end example
-@noindent Now, list the contents of @file{practice} again:
-
-@example
-%ls
-practice
-@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.
-What happened to the files? When you created @file{~/music}, your
-working directory was your home directory. When you extracted
-@file{~/music}, your working directory was @file{~/practice}.
-@code{tar} stored the files in @file{practice} relative to your home
-directory, and then extracted them relative to @file{~/practice}. The
-files are now in a new subdirectory, called
-@file{~/practice/practice}.
+@chapter Invoking @code{tar}
-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:
+The usual way to invoke tar is
@example
-% rm ~/practice/practice/*
-% rmdir practice
-% cd ..
-% tar +extract +file=music practice
+@code{tar} @var{options}... [@var{file-or-member-names}...]
@end example
-@noindent (@code{tar} will report that it is unable to create the
-directory @file{~/practice} because it already exists. This will not
-effect the extraction of the other archive members.)
-
-@node Listing Archive Contents, Adding to Archives, Creating Archives, Tutorial
-@section Listing the Contents of an Archive
-
-Use @samp{+list} or @samp{-t} to print the names of files stored in an
-archive. If you use file-name arguments with this operation,
-@code{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,
-@code{tar} also prints the names of all underlying files, including
-sub-directories. If you use no file-name arguments, @code{tar} prints
-the names of all the archive members.
-
-You can use @samp{+list} with the @samp{+verbose} option to print
-archive members' attributes (owner, size, etc.).
+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
-* Listing names:: Listing the names of stored files
-* Additional File Info:: Getting Additional File Information
-* Specific File:: List A Specific File in an Archive
-* Listing Directories:: Listing the Contents of a Stored Directory
+* Option Form:: The Forms of Arguments
+* Argument Functions:: The Functions of Arguments
+* Old Syntax for Commands:: An Old, but Still Supported, Syntax
+ for @code{tar} Commands
@end menu
-@node Listing names, Additional File Info, Listing Archive Contents, Listing Archive Contents
-@subsection Listing the names of stored files
+@section The Forms of Arguments
-To list the names of files stored in an archive, use the @samp{+list}
-operation of @code{tar}.
+Most options of @code{tar} have a single letter form (a single letter
+preceded by @samp{-}), and at least one mnemonic form (a word or
+abbreviation preceded by @samp{--}). The forms are absolutely
+identical in function. For example, you can use either @samp{tar -t}
+or @samp{tar --list} to list the contents of an archive. In addition,
+mnemonic names can be given unique abbreviations. For example,
+@samp{--cre} can be used in place of @samp{--create} because there is
+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.
+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}.
-In a previous example, you created the archive @file{~/music}. To
-list the contents of @file{music}, while in your home directory:
+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
+@samp{tar --create -f george}. However, @code{tar} operations and
+options are case sensitive. You would not type the above example as
+@samp{tar -C --file=george}, because @samp{-C} is an option that
+causes @code{tar} to change directories, not an operation that creates
+an archive. In fact, @samp{-C} requires a further argument (the name
+of the directory which to change to). In this case, tar would think
+it needs to change to a directory named @samp{--file=george}, and
+wouldn't interpret @samp{--file-george} as an option at all!
-@itemize @bullet
-@item
-List the contents of an archive (@samp{tar -t} or @samp{tar +list})
+@section The Functions of Arguments
-@item
-Specify the archive to be listed (@samp{-f @var{archive-name}} or
-@samp{+file=@var{archive-name}}) @refill
-@end itemize
+You must give exactly one option from the following list to tar. This
+option specifies the basic operation for @code{tar} to perform.
-Thus:
+@table samp
+@item --help
+Print a summary of the options to @code{tar} and do nothing else
-@example
-% tar +list +file=music
-practice/
-practice/blues
-practice/folk
-practice/jazz
-practice/records
-@end example
+@item --create
+@item -c
+Create a new archive
-@node Additional File Info, Specific File, Listing names, Listing Archive Contents
-@subsection Listing Additional File Information
+@item --catenate
+@item --concatenate
+@item -A
+Add the contents of one or more archives to another archive
-To get more information when you list the names of files stored in an
-archive, specify the @samp{+verbose} option in conjunction with
-@samp{tar +list}. @code{tar} will print archive member's file
-protection, owner and group ID, size, and date and time of creation.
+@item --append
+@item -a
+Add files to an existing archive
-For example:
+@item --list
+@item -t
+List the members in an archive
-@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/records
-%
-@end example
+@item --delete
+Delete members from an archive
-Note that when you use @samp{+verbose} with @samp{+list}, @code{tar}
-doesn't print the names of files as they are being acted on, though
-the @samp{+verbose} option will have this effect when used with all
-other operations.
-
-@node Specific File, Comparing Files, Additional File Info, Listing Archive Contents
-@subsection List A Specific File in an Archive
-
-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
-@samp{+list} operation. For example, to see whether the file
-@file{folk} is in the archive file @file{music}, do the following:
-
-@itemize @bullet
-@item
-Invoke @code{tar}, and specify the @samp{+list} operation
-(@samp{+list} or @samp{-t}).
-
-@item
-Specify the archive file to be acted on (@samp{+file
-@var{archive-name}} or @samp{-f @var{archive-name}}).
-
-@item
-Specify the files to look for, by typing their names as file-name
-arguments. You have to type the file name as it appears in the
-archive (normally, as it is relative to the relative to the directory
-from which the archive was created). <<< xref absolute-paths -ringo
-@end itemize
+@item --extract
+@item --get
+@item -x
+Extract members from an archive
-Type:
+@item --compare
+@item --diff
+@item -d
+Compare members in an archive with files in the file system
-@example
-% tar +list +file=music practice/folk
-@end example
+@item --update
+@item -u
+Update an archive by appending newer versions of already stored files
+@end itemize
-@noindent
-@code{tar} responds:
+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 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 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.
+
+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}.
-@example
-practice/folk
-@end example
+@section An Old, but Still Supported, Syntax for @code{tar} Commands
-@noindent
-If the file were not stored in the archive (for example, the file
-@file{practice/rock}), the example above would look like:
+For historical reasons, GNU @code{tar} also accepts a syntax for
+commands which splits options that require additional arguments into
+two parts. That syntax is of the form:
@example
-% tar +list +file=music practice/rock
-tar: practice/rock not found in archive
+@code{tar} @var{option-letters}... [@var{option-arguments}...] [@var{file-names}...]@refill
@end example
@noindent
-If you had used @samp{+verbose} mode, the example above would look
-like:
-
-@example
-% tar +list +file=music practice/folk
--rw-rw-rw- myself/user 62 May 23 10:55 1990 practice/folk
-@end example
-
-@node Listing Directories, , ,
-@subsection Listing the Contents of a Stored Directory
-
-To get information about the contents of an archived directory, use
-the directory name as a file-name argument in conjunction with
-@samp{+list}. To find out file attributes, include the
-@samp{+verbose} option.
-
-For example, to find out about files in the directory @file{practice},
-in the archive file @file{music}, type:
-
-@example
-% tar +list +file=music practice
-@end example
-
-@noindent @code{tar} responds:
-
-@example
-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/records
-@end example
-
-When you use a directory name as a file-name argument, @code{tar} acts
-on all the files (including sub-directories) in that directory.
-
-@node Comparing Files, , ,
-@section Comparing Files in an Archive with Files in the File System
-
-To compare the attributes of archive members with the attributes of
-their counterparts in the file system, use the @samp{+compare},
-@samp{+diff}, or @samp{-d}) operation. While you could use
-@samp{+list +verbose} to manually compare some file attributes, it is
-simpler to have @code{tar} itself compare file attributes and report
-back on file differences.
-@c <<<"manually"? suggestions? -ringo
-
-The @samp{+compare} 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.
-@samp{tar +compare} acts only on archive members---it ignores files in
-the file system that are not stored in the archive. If you give
-@samp{tar +compare} a file-name argument that does not correspond to
-the name of an archive member, @code{tar} responds with an error
-message.
-
-To compare archive members in the archive file @file{records} with
-files in the @file{~/practice} directory, first change into the
-@file{practice} directory. Then:
-
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{+compare} operation.
-(@samp{+compare}, @samp{+diff}, or @samp{-d}).
-
-@item
-Specify the archive where the files to be compared are stored
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
-
-@item
-Specify the archive members to be compared. (In this example you are
-comparing all the archive members in the archive. Since this is the
-default, you don't need to use any file-name arguments).
-@end itemize
-
-@example
-% tar +compare +file=records
-%
-@end example
+where arguments to the options appear in the same order as the letters
+to which they correspond, and the operation and all the option letters
+appear as a single argument, without separating spaces.
-@noindent
-While it looks like nothing has happened, @code{tar} has, in fact,
-done the comparison---and found nothing to report.
+This command syntax is useful because it lets you type the single
+letter forms of the operation and options as a single argument to
+@code{tar}, without writing preceding @samp{-}s or inserting spaces
+between letters. @samp{tar cv} or @samp{tar -cv} are equivalent to
+@samp{tar -c -v}.
-Use the @samp{+verbose} option to list the names of archive members as
-they are being compared with their counterparts of the same name in
-the file system:
+On the other hand, this old style syntax makes it difficult to match
+option letters with their corresponding arguments, and is often
+confusing. In the command @samp{tar cvbf 20 /dev/rmt0}, for example,
+@samp{20} is the argument for @samp{-b}, @samp{/dev/rmt0} is the
+argument for @samp{-f}, and @samp{-v} does not have a corresponding
+argument. The modern syntax---@samp{tar -c -v -b 20 -f
+/dev/rmt0}---is clearer.
-@example
-% tar +compare +verbose +file=records
-blues
-folk
-jazz
-%
-@end example
+@chapter Basic @code{tar} Operations
-@noindent
-If @code{tar} had had anything to report, it would have done so as it
-was comparing each file.
+This chapter describes the basic operations supported by the @code{tar}
+program. A given invocation of @code{tar} will do exactly one of these
+operations.
-If you remove the file @file{jazz} from the file system (@samp{rm
-jazz}), and modify the file @file{blues} (for instance, by adding text
-to it with an editor such as Emacs), the above example would look
-like:
+@section Creating a New Archive
-@example
-% tar +compare +verbose +file=records
-blues
-blues: mod time differs
-blues: size differs
-folk
-jazz
-jazz: does not exist
-%
-@end example
+The @samp{--create} (@code{-c}) option causes @code{tar} to create a new
+archive. The files to be archived are then named on the command line.
+Each file will be added to the archive with a member name exactly the
+same as the name given on the command line. (When you give an absolute
+file name @code{tar} actually modifies it slightly, @ref{Absolute
+Paths}.) If you list no files to be archived, then an empty archive is
+created.
-Note again that while @samp{tar +compare} reports the names of archive
-members that do not have counterparts in the file system, @samp{tar
-+compare} ignores files in the file system that do not have
-counterparts in the archive. To demonstrate this, create a file in
-the @file{practice} directory called @file{rock} (using any text
-editor). The new file appears when you list the directory's contents:
+If there are two many files to conveniently list on the command line,
+you can list the names in a file, and @code{tar} will read that file.
+@xref{Reading Names from a File}.
-@example
-% ls
-blues folk records rock
-@end example
+If you name a directory, then @code{tar} will archive not only the
+directory, but all its contents, recursively. For example, if you name
+@file{/}, then @code{tar} will archive the entire filesystem.
-@noindent
-If you type the @samp{+compare} example again, @code{tar} prints the
-following:
+Do not use the option to add files to an existing archive; it will
+delete the archive and write a new one. Use @samp{--append} instead.
+(@xref{Adding to an Existing Archive}.)
-@example
-% tar +compare +verbose +file=records
-blues
-blues: mod time differs
-blues: size differs
-folk
-jazz
-jazz: does not exist
-%
-@end example
+There are various ways of causing @code{tar} to skip over some files,
+and not archive them. @xref{Specifying Names to @code{tar}}.
-@noindent
-@code{tar} ignores the file @file{rock} because @code{tar} is
-comparing archive members to files in the file system, not vice versa.
+@section Adding to an Existing Archive
-If you specify @file{rock} explicitly (using a file-name argument),
-@code{tar} prints an error message:
+The @samp{--append} (@code{-r}) option will case @code{tar} to add new
+files to an existing archive. It interprets file names and member names
+in exactly the same manner as @samp{--create}. Nothing happens if you
+don't list any names.
-@example
-% tar +compare +verbose +file=records rock
-tar: rock not found in archive
-%
-@end example
+This option never deletes members. If a new member is added under the
+same name as an existing member, then both will be in the archive, with
+the new member after the old one. For information on how this affects
+reading the archive, @ref{Multiple Members with the Same Name}.
-@menu
-* Comparing Directories:: Using Compare on Directories
-@end menu
+This operation cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats thoes tape drives use.
-@node Comparing Directories, , ,
-@subsubsection Using Compare on Directories
+@section Combining Archives
-In addition to using @samp{+compare} to compare text files, you can
-use @samp{+compare} to compare directories. To illustrate this,
-re-create the examples above using your home directory as the working
-directory, and using the archive file @file{~/music} instead of the
-archive file @file{~/practice/records}.
+The @samp{--catenate} (or @code{--concatenate}, or @code{-A}) causes
+@code{tar} to add the contents of several archives to an existing
+archive.
-First, change into your home directory (@samp{cd ~}). Then, try the
-above example using @file{music} as the specified archive file, and
-@file{practice} as a file-name argument.
+Name the archives to be catenated on the command line. (Nothing happens
+if you don't list any.) The members, and their member names, will be
+copied verbatim from those archives. If this causes multiple members to
+have the same name, it does not delete either; all the members with the
+same name coexist. For information on how this affects reading the
+archive, @ref{Multiple Members with the Same Name}.
-@example
-% tar +compare +verbose +file=music practice
-@end example
+You must use this option to concatenate archives. If you just combine
+them with @code{cat}, the result will not be a valid @code{tar} format
+archive.
-@noindent
-If you have been following along with the tutorial, @code{tar} will
-respond:
+This operation cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats thoes tape drives use.
-@example
-practice
-practice/blues
-practice/blues: mod time differs
-practice/blues: size differs
-practice/folk
-practice/jazz
-practice/jazz: does not exist
-practice/records
-@end example
+@section Removing Archive Members
-@node Adding to Archives, Concatenate, Listing Archive Contents, Tutorial
-@section Adding Files to Existing Archives
+You can use the @samp{--delete} option to remove members from an
+archive. Name the members on the command line to be deleted. This
+option will rewrite the archive; because of this, it does not work on
+tape drives. If you list no members to be deleted, nothing happens.
-@c >>> we want people to use the script for backups, so I an not going to
-@c >>> use backups as an explanation in the tutorial. (people can still
-@c >>> do it if they really want to) -ringo
+@section Listing Archive Members
-While you can use @code{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.
+The @samp{--list} (@samp{-t}) option will list the names of members of
+the archive. Name the members to be listed on the command line (to
+modify the way these names are interpreted, @pxref{Specifying Names to
+@code{tar}}). If you name no members, then @samp{--list} will list the
+names of all the members of the archive.
-To add new files to an existing archive, use the @samp{+add-file},
-@samp{+append} or @samp{-r} operation. To add newer versions of
-archive members to an archive, use the @samp{+update} or @samp{-u}
-operation.
+To see more th
-@menu
-* Append:: Appending Files to an Archive
-* Update:: Updating Files in an Archive
-@end menu
-@node Append, Update, Adding to Archives, Adding to Archives
-@subsection Appending Files to an Archive
-
-The simplest method of adding a file to an existing archive is the
-@samp{+add-file}, @samp{-r} or @samp{+append} operation, which writes
-files into the archive without regard to whether or not they are
-already archive members. When you use @samp{+add-file} you must use
-file-name arguments; there is no default. If you specify a file that
-is already stored in the archive, @code{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 @file{~/practice/rock} which has not been stored in
-either the archive file @file{~/practice/records}, or the archive file
-@file{~/music}. To add @file{rock} to @file{records}, first make
-@file{practice} the working directory (@samp{cd practice}). Then:
-
-@itemize @bullet
-@item
-Invoke @code{tar} and specify the @samp{+add-file} operation
-(@samp{+add-file}, @samp{-r} or @samp{+append})
-
-@item
-Specify the archive to which the file will be added
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
-
-@item
-Specify the files to be added to the archive, using file-name
-arguments
-@end itemize
+@chapter Specifying Names to @code{tar}
-@noindent
-For example:
+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.
-@example
-% tar +add-file +file=records rock
-@end example
+@section Reading Names from a File
-@noindent
-If you list the archive members in @file{records}, you will see that
-@file{rock} has been added to the archive:
+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.
-@example
-% tar +list +file=records
-blues
-folk
-jazz
-rock
-@end example
+@xref{Regular Expressions} for more information on the syntax and
+meaning of regular expressions.
-@c <<< this should be some kind of node.
+@section Operating Only on New Files
-You can use @samp{+add-file} to keep archive members current with
-active files. Because @samp{+add-file} stores a file whether or not
-there is already an archive member with the same file name, you can
-use @samp{+add-file} 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 @samp{tar +extract} 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.
+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 recall from the examples using @samp{+compare} above,
-@file{blues} was changed after the archive @file{records} was created.
-It is simple, however, to use @samp{+add-file} to add the new version
-of @file{blues} to @file{records}:
+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.
-@example
-% tar +add-file +verbose +file=records blues
-blues
-@end example
+You should never use this option for making incremental dumps. To learn
+how to use @code{tar} to make backups, @ref{Making Backups}.
-@noindent
-If you now list the contents of the archive, you will obtain the following:
+@section Crossing Filesystem Boundaries
-@example
-% tar +list -f records
-blues
-folk
-jazz
-rock
-blues
-@end example
+The @samp{--one-file-system} option causes @code{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same filesystem as the directory itself
+(because it is a mounted filesystem in its own right), then @code{tar}
+will not archive that file, or (if it is a directory itself) anything
+beneath it.
-@noindent
-The newest version of @file{blues} is at the end of the archive. When
-the files in @file{records} are extracted, the newer version of
-@file{blues} (which has the same name as the older) will overwrite the
-version stored first. When @samp{tar +extract} is finished, only the
-newer version of @file{blues} is in the file system. <<<xref
-keep-old-files>>>
-
-@node Update, , Append, Adding to Archives
-@subsection Updating Files in an Archive
-
-To keep archive members up to date with their counterparts of the same
-name in the file system, use the @samp{+update} or @samp{-u}
-operation. @samp{tar +update} 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, @code{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,
-@code{tar} reports an error.
-
-You could use the @samp{+add-file} option to keep an archive current,
-but do so you would either have to use the @samp{+compare} and
-@samp{+list} 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 @samp{+update}
-operation---if you don't specify any files, @code{tar} won't act on
-any files.
-
-To see the @samp{+update} option at work, create a new file,
-@file{~/practice/classical}, and modify the file
-@file{~/practice/blues} (you can use a text editor, such as Emacs, to
-do both these things). Then, with @file{practice} as your working
-directory, invoke @samp{tar +update} using the names of all the files
-in the practice directory as file-name arguments, and specifying the
-@samp{+verbose} option:
+This does not necessarily limit @code{tar} to only archiving the
+contents of a single filesystem, because all files named on the command
+line (or through the @samp{--files-from} option) will always be
+archived.
-@example
-% tar +update +verbose +file=records blues folk rock classical
-blues
-classical
-%
-@end example
+@chapter Changing the Names of Members when Archiing
-@noindent
-Because you specified verbose mode, @code{tar} printed out the names
-of the files it acted on. If you now list the archive members of the
-archive, (@samp{tar +list +file=records}), you will see that the file
-@file{classical} and another version of the file @file{blues} have
-been added to @file{records}.
-
-Note: When you update an archive, @code{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.
-
-@node Concatenate, Extracting Files Example, Adding to Archives, Tutorial
-@comment node-name, next, previous, up
-@section Concatenating Archives
-
-To concatenate archive files, use @samp{tar +concatenate} or @samp{tar
--A}. This operation adds other archives to the end of an archive.
-While it may seem intuitive to concatenate archives using @code{cat},
-the utility for adding files together, archive files which have been
-"catted" together cannot be read properly by @code{tar}. Archive
-files incorporate an end of file marker---if archives are concatenated
-using @code{cat}, this marker will appear before the end of the new
-archive. This will interfere with operations on that archive.
-@c <<<xref ignore-zeros>>>
-
-In earlier examples, you stored the @file{~/practice} directory in an
-archive file, @file{~/music}. If you have been following the
-examples, you have since changed the contents of the @file{~/practice}
-directory. There is a current version of the files in the
-@file{practice} directory, however, stored in the archive file
-@file{~/practice/records}.
-
-To store current versions of the files in @file{practice} in the
-archive file @file{music}, you can use @samp{tar +concatenate} to add
-the archive file @file{~/practice/records} to @file{music}. First,
-make sure you are in your home directory (@samp{cd ~}). Then:
-
-@itemize @bullet
-@item
-Invoke @code{tar}, and specify the @samp{+concatenate} operation
-(@samp{-A} or @samp{+concatenate})
-
-@item
-Specify the archive file to be added to
-(@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
-
-@item
-Specify the archives to be added, using file-name arguments. In this
-case, the file-name arguments are, unusually, the names of archive
-files. (Remember to include the path in the archive name, if the
-archive file is not in your working directory.)
-@end itemize
+@section Changing Directory
+The @samp{--directory=@var{directory}} (@samp{-C @var{directory}})
+option causes @code{tar} to change its current working directory to
+@var{directory}. Unlike most options, this one is processed at the
+point it occurs within the list of files to be processed. Consider the
+following command:
@example
-% cd ~
-% tar +concatenate +file=music practice/records
+tar --create --file=foo.tar -C /etc passwd hosts -C /lib libc.a
@end example
-If you now list the contents of the @file{music}, you see it now
-contains the archive members of @file{practice/records}:
+This command will place the files @file{/etc/passwd}, @file{/etc/hosts},
+and @file{/lib/libc.a} into the archive. However, the names of the
+archive members will be exactly what they were on the command line:
+@file{passwd}, @file{hosts}, and @file{libc.a}. The @samp{--directory}
+option is frequently used to make the archive independent of the
+original name of the directory holding the files.
-@example
-%tar +list +file=music
-blues
-folk
-jazz
-rock
-blues
-practice/blues
-practice/folk
-practice/jazz
-practice/rock
-practice/blues
-practice/classical
-@end example
+Note that @samp{--directory} options are interpreted consecutively. If
+@samp{--directory} option specifies a relative pathname, it is
+interpreted relative to the then current directory, which might not be
+the same as the original current working directory of @code{tar}, due to
+a previous @samp{--directory} option.
-@node Deleting Files, , , Tutorial
-@comment node-name, next, previous, up
-@section Deleting Files From an Archive
+When using @samp{--files-from} (@pxref{Reading Names from a File}), you
+can put @samp{-C} options in the file list. Unfortunately, you cannot
+put @samp{--directory} options in the file list. (This interpretation
+can be disabled by using the @samp{--null} option.)
-In some instances, you may want to remove some files from an archive
-stored on disk
+@section Absolute Path Names
-@quotation
-@emph{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.
-@end quotation
+When @code{tar} extracts archive members from an archive, it strips any
+leading slashes (@code{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
+@file{/etc/passwd}, @code{tar} will extract it as if the name were
+really @file{etc/passwd}.
-To remove archive members from an archive, use the @samp{+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.
+Other @code{tar} programs do not do this. As a result, if you create an
+archive whose member names start with a slash, they will be difficult
+for other people with an inferior @code{tar} program to use. Therefore,
+GNU @code{tar} also strips leading slashes from member names when
+putting members into the archive. For example, if you ask @code{tar} to
+add the file @file{/bin/ls} to an archive, it will do so, but the member
+name will be @file{bin/ls}.
-Execution of the @samp{+delete} operation can be very slow.
+If you use the @samp{--absolute-paths} option, @code{tar} will do
+neither of these transformations.
-To delete all versions of the file @file{blues} from the archive
-@file{records} in the @file{practice} directory, make sure you are in
-that directory, and then:
+@section Symbolic Links
-@itemize @bullet
-@item
-List the contents of the archive file @file{records} (see above for
-the steps involved) to insure that the file(s) you wish to delete are
-stored in the archive. (This step is optional)
+Normally, when @code{tar} archives a symbolic link, it writes a record
+to the archive naming the target of the link. In that way, the
+@code{tar} archive is a faithful record of the filesystem contents.
+However, if you want @code{tar} to actually dump the contents of the
+target of the symbolic link, then use the @samp{--dereference} option.
-@item
-Invoke @code{tar} and specify the @samp{+delete} operation
-(@samp{+delete}).
-@item
-Specify the name of the archive file that the file(s) will be deleted
-from (@samp{+file=@var{archive-name}} or @samp{-f @var{archive-name}})
-@item
-Specify the files to be deleted, using file-name arguments.
+XXXX MIB XXXX
-@item
-List the contents of the archive file again---note that the files have
-been removed. (this step is also optional)
-@end itemize
-@example
-% tar +list +file=records
-blues
-folk
-jazz
-% tar +delete +file=records blues
-% tar +list +file=records
-folk
-jazz
-%
-@end example
@node Wizardry, Archive Structure, Tutorial, Top
@chapter Wizardry
<<< the following using standard input/output correct??
@example
-cd sourcedirectory; tar +create +file=- . | (cd targetdir; tar +extract +file=-)
+cd sourcedirectory; tar --create --file=- . | (cd targetdir; tar --extract --file=-)
@end example
@noindent
Certain old versions of @code{tar} cannot handle additional
information recorded by newer @code{tar} programs. To create an
archive which can be read by these old versions, specify the
-@samp{+old-archive} option in conjunction with the @samp{tar +create}
+@samp{--old-archive} option in conjunction with the @samp{tar --create}
operation. When you specify this option, @code{tar} leaves out
information about directories, pipes, fifos, contiguous files, and
device files, and specifies file ownership by group and user ids
instead of names.
-The @samp{+old-archive} option is needed only if the archive must be
+The @samp{--old-archive} option is needed only if the archive must be
readable by an older tape archive program which cannot handle the new format.
Most @code{tar} programs do not have this limitation, so this option
is seldom needed.
@table @samp
-@item +old-archive
+@item --old-archive
@itemx -o
-@itemx +old
-@itemx +portable
+@itemx --old
+@itemx --portable
@c has portability been changed to portable?
Creates an archive that can be read by an old @code{tar} program.
-Used in conjunction with the @samp{tar +create} operation.
+Used in conjunction with the @samp{tar --create} operation.
@end table
@node Archive Label, Format Variations, Old Style File Information, Archive Structure
@cindex Labeling an archive
@cindex Labels on the archive media
-@c !! Should the arg to +label be a quoted string?? no - ringo
+@c !! Should the arg to --label be a quoted string?? no - ringo
To avoid problems caused by misplaced paper labels on the archive
media, you can include a @dfn{label} entry---an archive member which
contains the name of the archive---in the archive itself. Use the
-@samp{+label=@var{archive-label}} option in conjunction with the
-@samp{+create} operation to include a label entry in the archive as it
+@samp{--label=@var{archive-label}} option in conjunction with the
+@samp{--create} operation to include a label entry in the archive as it
is being created.
-If you create an archive using both @samp{+label=@var{archive-label}}
-and @samp{+multi-volume}, each volume of the archive will have an
+If you create an archive using both @samp{--label=@var{archive-label}}
+and @samp{--multi-volume}, each volume of the archive will have an
archive label of the form @samp{@var{archive-label} Volume @var{n}},
where @var{n} is 1 for the first volume, 2 for the next, and so on.
@xref{Multi-Volume Archives}, for information on creating multiple
volume archives.
-If you extract an archive using @samp{+label=@var{archive-label}},
+If you extract an archive using @samp{--label=@var{archive-label}},
@code{tar} will print an error if the archive label doesn't match the
@var{archive-label} specified, and will then not extract the archive.
You can include a regular expression in @var{archive-label}, in this
@c >>>specific group? ie for multi-volume??? -ringo
To find out an archive's label entry (or to find out if an archive has
-a label at all), use @samp{tar +list +verbose}. @code{tar} will print the
+a label at all), use @samp{tar --list --verbose}. @code{tar} will print the
label first, and then print archive member information, as in the
example below:
@example
-% tar +verbose +list +file=iamanarchive
+% tar --verbose --list --file=iamanarchive
V--------- 0/0 0 Mar 7 12:01 1992 iamalabel--Volume Header--
-rw-rw-rw- ringo/user 40 May 21 13:30 1990 iamafilename
@end example
@table @samp
-@item +label=@var{archive-label}
+@item --label=@var{archive-label}
@itemx -V @var{archive-label}
Includes an @dfn{archive-label} at the beginning of the archive when
the archive is being created (when used in conjunction with the
-@samp{tar +create} operation). Checks to make sure the archive label
+@samp{tar --create} operation). Checks to make sure the archive label
matches the one specified (when used in conjunction with the @samp{tar
-+extract} operation.
+--extract} operation.
@end table
-@c was +volume
+@c was --volume
@node Format Variations, , Archive Label, Archive Structure
@section Format Variations
you can use the options described in the following sections. If you
do not specify any format parameters, @code{tar} uses default
parameters. You cannot modify a compressed archive. If you create an
-archive with the @samp{+block-size} option specified (@pxref{Blocking
+archive with the @samp{--block-size} option specified (@pxref{Blocking
Factor}), you must specify that block-size when operating on the
archive. @xref{Matching Format Parameters}, for other examples of
format parameter considerations.
@cindex Multi-volume archives
To create an archive that is larger than will fit on a single unit of
-the media, use the @samp{+multi-volume} option in conjunction with the
-@samp{tar +create} operation (@pxref{Creating Archives}). A
+the media, use the @samp{--multi-volume} option in conjunction with the
+@samp{tar --create} operation (@pxref{Creating Archives}). A
@dfn{multi-volume} archive can be manipulated like any other archive
-(provided the @samp{+multi-volume} option is specified), but is stored
+(provided the @samp{--multi-volume} option is specified), but is stored
on more than one tape or disk.
-When you specify @samp{+multi-volume}, @code{tar} does not report an
+When you specify @samp{--multi-volume}, @code{tar} does not report an
error when it comes to the end of an archive volume (when reading), or
the end of the media (when writing). Instead, it prompts you to load
a new storage volume. If the archive is on a magnetic tape, you
You can read each individual volume of a multi-volume archive as if it
were an archive by itself. For example, to list the contents of one
-volume, use @samp{tar +list}, without @samp{+multi-volume} specified.
+volume, use @samp{tar --list}, without @samp{--multi-volume} specified.
To extract an archive member from one volume (assuming it is described
-that volume), use @samp{tar +extract}, again without
-@samp{+multi-volume}.
+that volume), use @samp{tar --extract}, again without
+@samp{--multi-volume}.
If an archive member is split across volumes (ie. its entry begins on
one volume of the media and ends on another), you need to specify
-@samp{+multi-volume} to extract it successfully. In this case, you
+@samp{--multi-volume} to extract it successfully. In this case, you
should load the volume where the archive member starts, and use
-@samp{tar +extract +multi-volume}---@code{tar} will prompt for later
+@samp{tar --extract --multi-volume}---@code{tar} will prompt for later
volumes as it needs them. @xref{Extracting From Archives} for more
information about extracting archives.
-@samp{+info-script=@var{program-file}} is like @samp{+multi-volume},
+@samp{--info-script=@var{program-file}} is like @samp{--multi-volume},
except that @code{tar} does not prompt you directly to change media
volumes when a volume is full---instead, @code{tar} runs commands you
have stored in @var{program-file}. This option can be used to
<<< end.
@table @samp
-@item +multi-volume
+@item --multi-volume
@itemx -M
Creates a multi-volume archive, when used in conjunction with
-@samp{tar +create}. To perform any other operation on a multi-volume
-archive, specify @samp{+multi-volume} in conjunction with that
+@samp{tar --create}. To perform any other operation on a multi-volume
+archive, specify @samp{--multi-volume} in conjunction with that
operation.
-@item +info-script=@var{program-file}
+@item --info-script=@var{program-file}
@itemx -F @var{program-file}
Creates a multi-volume archive via a script. Used in conjunction with
-@samp{tar +create}.
+@samp{tar --create}.
@end table
@node Sparse Files, Blocking Factor, Multi-Volume Archives, Format Variations
A file is sparse if it contains blocks of zeros whose existance is
recorded, but that have no space allocated on disk. When you specify
-the @samp{+sparse} option in conjunction with the @samp{+create}
+the @samp{--sparse} option in conjunction with the @samp{--create}
operation, @code{tar} tests all files for sparseness while archiving.
If @code{tar} finds a file to be sparse, it uses a sparse
representation of the file in the archive. @xref{Creating Archives},
for more information about creating archives.
-@samp{+sparse} is useful when archiving files, such as dbm files,
+@samp{--sparse} is useful when archiving files, such as dbm files,
likely to contain many nulls. This option dramatically
decreases the amount of space needed to store such an archive.
@quotation
-@strong{Please Note:} Always use @samp{+sparse} when performing file
+@strong{Please Note:} Always use @samp{--sparse} when performing file
system backups, to avoid archiving the expanded forms of files stored
sparsely in the system.@refill
Even if your system has no no sparse files currently, some may be
-created in the future. If you use @samp{+sparse} while making file
+created in the future. If you use @samp{--sparse} while making file
system backups as a matter of course, you can be assured the archive
will always take no more space on the media than the files take on
disk (otherwise, archiving a disk filled with sparse files might take
<<< xref incremental when node name is set.
@end quotation
-@code{tar} ignores the @samp{+sparse} option when reading an archive.
+@code{tar} ignores the @samp{--sparse} option when reading an archive.
@table @samp
-@item +sparse
+@item --sparse
@itemx -S
Files stored sparsely in the file system are represented sparsely in
the archive. Use in conjunction with write operations.
Records are read and written in whole number multiples called
@dfn{blocks}. The number of records in a block (ie. the size of a
block in units of 512 bytes) is called the @dfn{blocking factor}. The
-@samp{+block-size=@var{number}} option specifies the blocking factor
+@samp{--block-size=@var{number}} option specifies the blocking factor
of an archive. The default blocking factor is typically 20 (ie.@:
10240 bytes), but can be specified at installation. To find out the
-blocking factor of an existing archive, use @samp {tar +list
-+file=@var{archive-name}}. This may not work on some devices.
+blocking factor of an existing archive, use @samp {tar --list
+--file=@var{archive-name}}. This may not work on some devices.
Blocks are seperated by gaps, which waste space on the archive media.
If you are archiving on magnetic tape, using a larger blocking factor
you must specify the same blocking factor when you modify that
archive. Some archive devices will also require you to specify the
blocking factor when reading that archive, however this is not
-typically the case. Usually, you can use @samp{tar +list} without
+typically the case. Usually, you can use @samp{tar --list} without
specifying a blocking factor---@code{tar} reports a non-default block
size and then lists the archive members as it would normally. To
extract files from an archive with a non-standard blocking factor
(particularly if you're not sure what the blocking factor is), you can
-usually use the {+read-full-blocks} option while specifying a blocking
+usually use the {--read-full-blocks} option while specifying a blocking
factor larger then the blocking factor of the archive (ie. @samp{tar
-+extract +read-full-blocks +block-size=300}. @xref{Listing Contents}
-for more information on the @samp{+list} operation.
+--extract --read-full-blocks --block-size=300}. @xref{Listing Contents}
+for more information on the @samp{--list} operation.
@xref{read-full-blocks} for a more detailed explanation of that
option.
@table @samp
-@item +block-size=@var{number}
+@item --block-size=@var{number}
@itemx -b @var{number}
Specifies the blocking factor of an archive. Can be used with any
-operation, but is usually not necessary with @samp{tar +list}.
+operation, but is usually not necessary with @samp{tar --list}.
@end table
@node Compressed Archives, , Blocking Factor, Format Variations
@cindex Compressed archives
@cindex Storing archives in compressed format
-@samp{+compress} indicates an archive stored in compressed format.
-The @samp{+compress} option is useful in saving time over networks and
+@samp{--compress} indicates an archive stored in compressed format.
+The @samp{--compress} option is useful in saving time over networks and
space in pipes, and when storage space is at a premium.
-@samp{+compress} causes @code{tar} to compress when writing the
+@samp{--compress} causes @code{tar} to compress when writing the
archive, or to uncompress when reading the archive.
To perform compression and uncompression on the archive, @code{tar}
runs the @code{compress} utility. @code{tar} uses the default
compression parameters; if you need to override them, avoid the
-@samp{+compress} option and run the @code{compress} utility
+@samp{--compress} option and run the @code{compress} utility
explicitly. It is useful to be able to call the @code{compress}
utility from within @code{tar} because the @code{compress} utility by
itself cannot access remote tape drives.
-The @samp{+compress} option will not work in conjunction with the
-@samp{+multi-volume} option or the @samp{+add-file}, @samp{+update},
-@samp{+add-file} and @samp{+delete} operations. @xref{Modifying}, for
+The @samp{--compress} option will not work in conjunction with the
+@samp{--multi-volume} option or the @samp{--add-file}, @samp{--update},
+@samp{--add-file} and @samp{--delete} operations. @xref{Modifying}, for
more information on these operations.
If there is no compress utility available, @code{tar} will report an
error.
-@samp{+compress-block} is like @samp{+compress}, but when used in
-conjunction with @samp{+create} also causes @code{tar} to pad the last
+@samp{--compress-block} is like @samp{--compress}, but when used in
+conjunction with @samp{--create} also causes @code{tar} to pad the last
block of the archive out to the next block boundary as it is written.
This is useful with certain devices which require all write operations
be a multiple of a specific size.
@end quotation
@table @samp
-@item +compress
-@itemx +uncompress
+@item --compress
+@itemx --uncompress
@itemx -z
@itemx -Z
When this option is specified, @code{tar} will compress (when writing
an archive), or uncompress (when reading an archive). Used in
-conjunction with the @samp{+create}, @samp{+extract}, @samp{+list} and
-@samp{+compare} operations.
+conjunction with the @samp{--create}, @samp{--extract}, @samp{--list} and
+@samp{--compare} operations.
-@item +compress-block
+@item --compress-block
@itemx -z -z
-Acts like @samp{+compress}, but pads the archive out to the next block
+Acts like @samp{--compress}, but pads the archive out to the next block
boundary as it is written when used in conjunction with the
-@samp{+create} operation.
+@samp{--create} operation.
@end table
@c >>> MIB -- why not use -Z instead of -z -z ? -ringo
@node Reading and Writing, Insuring Accuracy, Archive Structure, Top
@chapter Reading and Writing Archives
-The @samp{+create} operation writes a new archive, and the
-@samp{+extract} operation reads files from an archive and writes them
+The @samp{--create} operation writes a new archive, and the
+@samp{--extract} operation reads files from an archive and writes them
into the file system. You can use other @code{tar} operations to
write new information into an existing archive (adding files to it,
adding another archive to it, or deleting files from it), and you can
read a list of the files in an archive without extracting it using the
-@samp{+list} operation.
+@samp{--list} operation.
@menu
* Archive Name:: The name of an archive
An archive can be saved as a file in the file system, sent through a
pipe or over a network, or written to an I/O device such as a tape or
disk drive. To specify the name of the archive, use the
-@samp{+file=@var{archive-name}} option.
+@samp{--file=@var{archive-name}} option.
An archive name can be the name of an ordinary file or the name of an
I/O device. @code{tar} always needs an archive name---if you do not
use the following:
@example
-+file=@var{hostname}:/@var{dev}/@var{file name}
+--file=@var{hostname}:/@var{dev}/@var{file name}
@end example
@noindent
@code{tar} will complete the remote connection, if possible, and
prompt you for a username and password. If you use
-@samp{+file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @code{tar}
+@samp{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @code{tar}
will complete the remote connection, if possible, using your username
as the username on the remote machine.
@c >>>MIB --- is this clear?
@table @samp
-@item +file=@var{archive-name}
+@item --file=@var{archive-name}
@itemx -f @var{archive-name}
Names the archive to create or operate on. Use in conjunction with
any operation.
@cindex Writing new archives
@cindex Archive creation
-To create an archive, use @samp{tar +create}. To name the archive,
-use @samp{+file=@var{archive-name}} in conjunction with the
-@samp{+create} operation (@pxref{Archive Name}). If you do not name
+To create an archive, use @samp{tar --create}. To name the archive,
+use @samp{--file=@var{archive-name}} in conjunction with the
+@samp{--create} operation (@pxref{Archive Name}). If you do not name
the archive, @code{tar} uses the value of the environment variable
@code{TAPE} as the file name for the archive, or, if that is not
available, @code{tar} uses a default archive name, usually that for tape
containing the files @file{larry}, @file{moe} and @file{curley}:
@example
-tar +create +file=stooges larry moe curley
+tar --create --file=stooges larry moe curley
@end example
If you specify a directory name as a file-name argument, @code{tar}
contents of the directory @file{marx}:
@example
-tar +create +file=hail/hail/fredonia marx
+tar --create --file=hail/hail/fredonia marx
@end example
If you don't specify files to put in the archive, @code{tar} archives
directory:
@example
-tar +create +file=home
+tar --create --file=home
@end example
@xref{File Name Lists}, for other ways to specify files to archive.
stored, or delete archive members already stored.
To find out what files are already stored in an archive, use @samp{tar
-+list +file=@var{archive-name}}. @xref{Listing Contents}.
+--list --file=@var{archive-name}}. @xref{Listing Contents}.
@menu
* Adding Files::
@cindex Adding files to an archive
@cindex Updating an archive
-To add files to an archive, use @samp{tar +add-file}. The archive to
+To add files to an archive, use @samp{tar --add-file}. The archive to
be added to must already exist and be in proper archive format (which
normally means it was created previously using @code{tar}). If the
archive was created with a different block size than now specified,
@file{stooges} created above:
@example
-tar +add-file +file=stooges shemp
+tar --add-file --file=stooges shemp
@end example
You must specify the files to be added; there is no default.
-@samp{tar +update} acts like @samp{tar +add-file}, but does not add
+@samp{tar --update} acts like @samp{tar --add-file}, but does not add
files to the archive if there is already a file entry with that name
in the archive that has the same modification time.
-Both @samp{+update} and @samp{+add-file} work by adding to the end of
+Both @samp{--update} and @samp{--add-file} work by adding to the end of
the archive. When you extract a file from the archive, only the
version stored last will wind up in the file system. Because
-@samp{tar +extract} extracts files from an archive in sequence, and
+@samp{tar --extract} extracts files from an archive in sequence, and
overwrites files with the same name in the file system, if a file name
appears more than once in an archive the last version of the file will
overwrite the previous versions which have just been extracted. You
should avoid storing older versions of a file later in the archive.
-Note: @samp{+update} is not suitable for performing backups, because
+Note: @samp{--update} is not suitable for performing backups, because
it doesn't change directory content entries, and because it lengthens
the archive every time it is used.
@c <<< xref to scripted backup, listed incremental, for info on backups.
@cindex Concatenating Archives
To append copies of an archive or archives to the end of another
-archive, use @samp{tar +add-archive}. The source and target archives
+archive, use @samp{tar --add-archive}. The source and target archives
must already exist and have been created using compatable format
parameters (@pxref{Matching Format Parameters}).
@code{tar} will stop reading an archive if it encounters an
end-of-archive marker. The @code{cat} utility does not remove
end-of-archive markers, and is therefore unsuitable for concatenating
-archives. @samp{tar +add-archive} removes the end-of-archive marker
+archives. @samp{tar --add-archive} removes the end-of-archive marker
from the target archive before each new archive is appended.
@c <<< xref ignore-zeros
You must specify the source archives using
-@samp{+file=@var{archive-name}} (@pxref{Archive Name}). If you do not
+@samp{--file=@var{archive-name}} (@pxref{Archive Name}). If you do not
specify the target archive , @code{tar} uses the value of the
environment variable @code{TAPE}, or, if this has not been set, the
default archive name.
were created in examples above):
@example
-tar +add-archive +file=stooges hail/hail/fredonia
+tar --add-archive --file=stooges hail/hail/fredonia
@end example
If you need to retrieve files from an archive that was added to using
-the @code{cat} utility, use the @samp{+ignore-zeros} option
+the @code{cat} utility, use the @samp{--ignore-zeros} option
(@pxref{Archive Reading Options}).
@node Deleting Archive Files, Matching Format Parameters, Appending Archives, Modifying
@cindex Deleting files from an archive
@cindex Removing files from an archive
-To delete archive members from an archive, use @samp{tar +delete}.
+To delete archive members from an archive, use @samp{tar --delete}.
You must specify the file names of the members to be deleted. All
archive members with the specified file names will be removed from the
archive.
@file{stooges}:
@example
-tar +delete +file=stooges curley
+tar --delete --file=stooges curley
@end example
-You can only use @samp{tar +delete} on an archive if the archive
+You can only use @samp{tar --delete} on an archive if the archive
device allows you to write to any point on the media.
@quotation
@c <<< MIB -- how about automatic detection of archive media? give error
@c <<< unless the archive device is either an ordinary file or different
-@c <<< input and output (+file=-).
+@c <<< input and output (--file=-).
@node Matching Format Parameters, , Deleting Archive Files, Modifying
@subsection Matching the Format Parameters
volume of the archive media (and new volumes, if needed). For all
other operations, you need to use the entire archive.
-If a multi-volume archive was labeled using @samp{+label}
+If a multi-volume archive was labeled using @samp{--label}
(@pxref{Archive Label}) when it was created, @code{tar} will not
automatically label volumes which are added later. To label
-subsequent volumes, specify @samp{+label=@var{archive-label}} again in
-conjunction with the @samp{+add-file}, @samp{+update} or
-@samp{+add-archive} operation.
+subsequent volumes, specify @samp{--label=@var{archive-label}} again in
+conjunction with the @samp{--add-file}, @samp{--update} or
+@samp{--add-archive} operation.
@cindex Labelling multi-volume archives
@c <<< example
@cindex Archive contents, list of
@cindex Archive members, list of
-@samp{tar +list} prints a list of the file names of the archive
+@samp{tar --list} prints a list of the file names of the archive
members on the standard output. If you specify @var{file-name}
-arguments on the command line (or using the @samp{+files-from} option,
+arguments on the command line (or using the @samp{--files-from} option,
@pxref{File Name Lists}), only the files you specify will be listed,
and only if they exist in the archive. Files not specified will be
ignored, unless they are under a specific directory.
-If you include the @samp{+verbose} option, @code{tar} prints an
+If you include the @samp{--verbose} option, @code{tar} prints an
@samp{ls -l} type listing for the archive. @pxref{Additional
-Information}, for a description of the @samp{+verbose} option.
+Information}, for a description of the @samp{--verbose} option.
If the blocking factor of the archive differs from the default,
@code{tar} reports this. @xref{Blocking Factor}.
@xref{Archive Reading Options} for a list of options which can be used
-to modify @samp{+list}'s operation.
+to modify @samp{--list}'s operation.
This example prints a list of the archive members of the archive
@file{stooges}:
@example
-tar +list +file=stooges
+tar --list --file=stooges
@end example
@noindent
archive file @file{dwarves}, which has a blocking factor of two:
@example
-tar +list -v +file=blocks
+tar --list -v --file=blocks
@end example
@noindent
@cindex Resurrecting files from an archive
To read archive members from the archive and write them into the file
-system, use @samp{tar +extract}. The archive itself is left
+system, use @samp{tar --extract}. The archive itself is left
unchanged.
If you do not specify the files to extract, @code{tar} extracts all
@file{stooges} into an empty directory:
@example
-tar +extract +file=stooges
+tar --extract --file=stooges
@end example
@noindent
If you wanted to just extract the files in the subdirectory
@file{marx}, you could specify that directory as a file-name argument
-in conjunction with the @samp{+extract} operation:
+in conjunction with the @samp{--extract} operation:
@example
-tar +extract +file=stooges marx
+tar --extract --file=stooges marx
@end example
@quotation
@strong{Warning:} Extraction can overwrite files in the file system.
To avoid losing files in the file system when extracting files from
-the archive with the same name, use the @samp{+keep-old-files} option
+the archive with the same name, use the @samp{--keep-old-files} option
(@pxref{File Writing Options}).
@end quotation
-If the archive was created using @samp{+block-size}, @samp{+compress}
-or @samp{+multi-volume}, you must specify those format options again
+If the archive was created using @samp{--block-size}, @samp{--compress}
+or @samp{--multi-volume}, you must specify those format options again
when extracting files from the archive (@pxref{Format Variations}).
@menu
return full blocks, or do not require the last block of an archive to
be padded out to the next block boundary. To keep reading until you
obtain a full block, or to accept an incomplete block if it contains
-an end-of-archive marker, specify the @samp{+read-full-blocks} option
-in conjunction with the @samp{+extract} or @samp{+list} operations.
+an end-of-archive marker, specify the @samp{--read-full-blocks} option
+in conjunction with the @samp{--extract} or @samp{--list} operations.
@xref{Listing Contents}.
-The @samp{+read-full-blocks} option is turned on by default when
+The @samp{--read-full-blocks} option is turned on by default when
@code{tar} reads an archive from standard input, or from a remote
machine. This is because on BSD Unix systems, attempting to read a
pipe returns however much happens to be in the pipe, even if it is
would fail as soon as it read an incomplete block from the pipe.
If you're not sure of the blocking factor of an archive, you can read
-the archive by specifying @samp{+read-full-blocks} and
-@samp{+block-size=@var{n}}, where @var{n} is a blocking factor larger
+the archive by specifying @samp{--read-full-blocks} and
+@samp{--block-size=@var{n}}, where @var{n} is a blocking factor larger
than the blocking factor of the archive. This lets you avoid having
to determine the blocking factor of an archive. @xref{Blocking
Factor}.
@table @samp
-@item +read-full-blocks
+@item --read-full-blocks
@item -B
-Use in conjunction with @samp{tar +extract} to read an archive which
+Use in conjunction with @samp{tar --extract} to read an archive which
contains incomplete blocks, or one which has a blocking factor less
than the one specified.
@end table
Normally @code{tar} stops reading when it encounters a block of zeros
between file entries (which usually indicates the end of the archive).
-@samp{+ignore-zeros} allows @code{tar} to completely read an archive
+@samp{--ignore-zeros} allows @code{tar} to completely read an archive
which contains a block of zeros before the end (i.e.@: a damaged
archive, or one which was created by @code{cat}-ing several archives
together).
-The @samp{+ignore-zeros} option is turned off by default because many
+The @samp{--ignore-zeros} option is turned off by default because many
versions of @code{tar} write garbage after the end of archive entry,
since that part of the media is never supposed to be read. GNU
@code{tar} does not write after the end of an archive, but seeks to
maintain compatablity among archiving utilities.
@table @samp
-@item +ignore-zeros
+@item --ignore-zeros
@itemx -i
To ignore blocks of zeros (ie.@: end-of-archive entries) which may be
encountered while reading an archive. Use in conjunction with
-@samp{tar +extract} or @samp{tar +list}.
+@samp{tar --extract} or @samp{tar --list}.
@end table
If you are using a machine with a small amount of memory, and you need
to process large list of file-names, you can reduce the amount of
space @code{tar} needs to process the list. To do so, specify the
-@samp{+same-order} option and provide an ordered list of file names.
+@samp{--same-order} option and provide an ordered list of file names.
This option tells @code{tar} that the @file{file-name} arguments
(provided on the command line, or read from a file using the
-@samp{+files-from} option) are listed in the same order as the files
+@samp{--files-from} option) are listed in the same order as the files
in the archive.
You can create a file containing an ordered list of files in the
-archive by storing the output produced by @samp{tar +list
-+file=@var{archive-name}}. @xref{Listing Contents}, for information
-on the @samp{+list} operation.
+archive by storing the output produced by @samp{tar --list
+--file=@var{archive-name}}. @xref{Listing Contents}, for information
+on the @samp{--list} operation.
This option is probably never needed on modern computer systems.
@table @samp
-@item +same-order
-@itemx +preserve-order
+@item --same-order
+@itemx --preserve-order
@itemx -s
To process large lists of file-names on machines with small amounts of
-memory. Use in conjunction with @samp{tar +compare}, @samp{tar +list}
-or @samp{tar +extract}.
+memory. Use in conjunction with @samp{tar --compare}, @samp{tar --list}
+or @samp{tar --extract}.
@end table
-@c we don't need/want +preserve to exist any more
+@c we don't need/want --preserve to exist any more
@node File Writing Options, Scarce Disk Space, Archive Reading Options, Extracting From Archives
@subsection Changing How @code{tar} Writes Files
without regard to the files already on the system---files with the
same name as archive members are overwritten. To prevent @code{tar}
from extracting an archive member from an archive, if doing so will
-overwrite a file in the file system, use @samp{+keep-old-files} in
-conjunction with the @samp{+extract} operation. When this option is
+overwrite a file in the file system, use @samp{--keep-old-files} in
+conjunction with the @samp{--extract} operation. When this option is
specified, @code{tar} reports an error stating the name of the files
in conflict, instead of writing the file from the archive.
@table @samp
-@item +keep-old files
+@item --keep-old files
@itemx -k
Prevents @code{tar} from overwriting files in the file system during
extraction.
setting.
To set the modification times of extracted files to the time when
-the files were extracted, use the @samp{+modification-time} option in
-conjunction with @samp{tar +extract}.
+the files were extracted, use the @samp{--modification-time} option in
+conjunction with @samp{tar --extract}.
@table @samp
-@item +modification-time
+@item --modification-time
@itemx -m
Sets the modification time of extracted archive members to the time
they were extracted, not the time recorded for them in the archive.
-Use in conjunction with @samp{+extract}.
+Use in conjunction with @samp{--extract}.
@end table
To set the modes (access permissions) of extracted files to those
recorded for those files in the archive, use the
-@samp{+preserve-permissions} option in conjunction with the
-@samp{+extract} operation.
+@samp{--preserve-permissions} option in conjunction with the
+@samp{--extract} operation.
@c <<<mib --- should be aliased to ignore-umask.
@table @samp
-@item +preserve-permission
-@itemx +same-permission
-@itemx +ignore-umask
+@item --preserve-permission
+@itemx --same-permission
+@itemx --ignore-umask
@itemx -p
Set modes of extracted archive members to those recorded in the
archive, instead of current umask settings. Use in conjunction with
-@samp{+extract}.
+@samp{--extract}.
@end table
@c <<< following paragraph needs to be rewritten:
@c <<< why doesnt' this cat files together, why is this useful. is it
@c <<< really useful with more than one file?
To write the files extracted to the standard output, instead of
-creating the files on the file system, use @samp{+to-stdout} in
-conjunction with @samp{tar +extract}. This option is useful if you
+creating the files on the file system, use @samp{--to-stdout} in
+conjunction with @samp{tar --extract}. This option is useful if you
are extracting files to send them through a pipe, and do not need to
preserve them in the file system.
@table @samp
-@item +to-stdout
+@item --to-stdout
@itemx -O
Writes files to the standard output. Used in conjunction with
-@samp{+extract}.
+@samp{--extract}.
@end table
@c <<< why would you want to do such a thing, how are files separated on
@cindex Space on the disk, recovering from lack of
If a previous attempt to extract files failed due to lack of disk
-space, you can use @samp{+starting-file=@var{file-name}} to start
+space, you can use @samp{--starting-file=@var{file-name}} to start
extracting only after file @var{file-name} when extracting files from
the archive. This assumes, of course, that there is now free space,
or that you are now extracting into a different file system.
@table @samp
-@item +starting-file=@var{file-name}
+@item --starting-file=@var{file-name}
@itemx -K @var{file-name}
Starts an operation in the middle of an archive. Use in conjunction
-with @samp{+extract} or @samp{+list}.
+with @samp{--extract} or @samp{--list}.
@end table
If you notice you are running out of disk space during an extraction
operation, you can also suspend @code{tar}, remove unnecessary files
from the file system, and then restart the same @code{tar} operation.
-In this case, @samp{+starting-file} is not necessary.
+In this case, @samp{--starting-file} is not necessary.
-@c <<< xref incremental, xref +interactive, xref +exclude
+@c <<< xref incremental, xref --interactive, xref --exclude
@node Insuring Accuracy, Selecting Archive Members, Reading and Writing, Top
@chapter Insuring the Accuracy of an Archive
@cindex Double-checking a write operation
To check for discrepancies in an archive immediately after it is
-written, use the @samp{+verify} option in conjunction with the
-@samp{tar +create} operation. When this option is specified,
+written, use the @samp{--verify} option in conjunction with the
+@samp{tar --create} operation. When this option is specified,
@code{tar} checks archive members against their counterparts in the file
system, and reports discrepancies on the standard error. In
multi-volume archives, each volume is verified after it is written,
drives, and some other devices cannot be verified.
@table @samp
-@item +verify
+@item --verify
@itemx -W
Checks for discrepancies in the archive immediately after it is
-written. Use in conjunction with @samp{tar +create}.
+written. Use in conjunction with @samp{tar --create}.
@end table
@node Comparing, , Write Verification, Insuring Accuracy
@section Comparing an Archive with the File System
@cindex Verifying the currency of an archive
-@samp{tar +compare} compares archive members in an existing archive
+@samp{tar --compare} compares archive members in an existing archive
with their counterparts in the file system, and reports differences in
file size, mode, owner, modification date and contents. If a file is
represented in the archive but does not exist in the file system,
@code{tar} reports a difference.
If you use @var{file-name} arguments in conjunction with @samp{tar
-+compare}, @code{tar} compares the archived versions of the files
+--compare}, @code{tar} compares the archived versions of the files
specified with their counterparts in the file system. If you specify
a file that is not in the archive, @code{tar} will report an error. If
you don't specify any files, @code{tar} compares all the files in the
of the same name in the file system.
@example
-tar +compare +file=stooges larry moe curly
+tar --compare --file=stooges larry moe curly
@end example
@noindent
If you do not specify files when @code{tar} is invoked, @code{tar}
operates on all the non-directory files in the working directory (if
-the operation is @samp{+create}), all the archive members in the
+the operation is @samp{--create}), all the archive members in the
archive (if a read operation is specified), or does nothing (if any
other operation is specified).
@cindex File-name arguments, alternatives
To read file names from a file on the file system, instead of from the
-command line, use the @samp{+files-from=@var{file}} option. If you
+command line, use the @samp{--files-from=@var{file}} option. If you
specify @samp{-} as @var{file}, the file names are read from standard
-input. Note that using both @samp{+files-from=-} and @samp{+file=-}
+input. Note that using both @samp{--files-from=-} and @samp{--file=-}
in the same command will not work unless the operation is
-@samp{+create}. @xref{Archive Name}, for an explanation of the
-@samp{+file} option.
+@samp{--create}. @xref{Archive Name}, for an explanation of the
+@samp{--file} option.
@table @samp
-@item +files-from=@var{file}
+@item --files-from=@var{file}
@itemx -T @var{file}
Reads file-name arguments from a file on the file system, instead of
from the command line. Use in conjunction with any operation.
@subsection Storing and Extracting Files Relative to Root
@c <<< is this what this does, or does it just preserve the slash?
-@c <<< is it still called +absolute-paths?
+@c <<< is it still called --absolute-paths?
@c To archive or extract files relative to the root directory, specify
-@c the @samp{+absolute-paths} option.
+@c the @samp{--absolute-paths} option.
@c Normally, @code{tar} acts on files relative to the working
@c directory---ignoring superior directory names when archiving, and
@c ignoring leading slashes when extracting.
-@c When you specify @samp{+absolute-paths}, @code{tar} stores file names
+@c When you specify @samp{--absolute-paths}, @code{tar} stores file names
@c including all superior directory names, and preserves leading slashes.
@c If you only invoked @code{tar} from the root directory you would never
-@c need the @samp{+absolute-paths} option, but using this option may be
+@c need the @samp{--absolute-paths} option, but using this option may be
@c more convenient than switching to root.
@c >>> should be an example in the tutorial/wizardry section using this
@c >>> is write access an issue?
@table @samp
-@item +absolute-paths
+@item --absolute-paths
Preserves full file names (inclusing superior dirctory names) when
archiving files. Preserves leading slash when extracting files.
@end table
To change working directory in the middle of a list of file names,
(either on the command line or in a file specified using
-@samp{+files-from}), use @samp{+directory=@var{directory}}. This will
+@samp{--files-from}), use @samp{--directory=@var{directory}}. This will
change the working directory to the directory @var{directory} after
that point in the list. For example,
@example
-tar +create iggy ziggy +directory=baz melvin
+tar --create iggy ziggy --directory=baz melvin
@end example
@noindent
precise name @file{melvin}, @emph{not} @file{baz/melvin}. Thus, the
archive will contain three files that all appear to have come from the
same directory; if the archive is extracted with plain @samp{tar
-+extract}, all three files will be written in the current directory.
+--extract}, all three files will be written in the current directory.
Contrast this with the command
@noindent
which records the third file in the archive under the name
@file{bar/melvin} so that, if the archive is extracted using @samp{tar
-+extract}, the third file will be written in a subdirectory named
+--extract}, the third file will be written in a subdirectory named
@file{bar}.
@table @samp
-@item +directory=@file{directory}
+@item --directory=@file{directory}
@itemx -C @file{directory}
Changes the working directory.
@end table
@cindex File names, using symbolic links
@cindex Symbolic link as file name
-@samp{+dereference} is used with @samp{tar +create}, and causes
+@samp{--dereference} is used with @samp{tar --create}, and causes
@code{tar} to archive files which are referenced by a symbolic link,
using the name of the link as the file name.
could be considered a bug.
@table @samp
-@item +dereference
+@item --dereference
@itemx -h
Stores files referenced by a symbolic link, using the name of the link
as the file name. Use in conjunction with any write operation.
@cindex Age, excluding files by
To avoid crossing file system boundaries when archiving parts of a
-directory tree, use @samp{+one-file-system}. This option only affects
+directory tree, use @samp{--one-file-system}. This option only affects
files that are archived because they are in a directory that is being
archived; files explicitly named on the command line are archived
regardless of where they reside.
This option is useful for making full or incremental archival backups
of a file system.
-If this option is used in conjunction with @samp{+verbose}, files that
+If this option is used in conjunction with @samp{--verbose}, files that
are excluded are mentioned by name on the standard error.
@table @samp
-@item +one-file-system
+@item --one-file-system
@itemx -l
Prevents @code{tar} from crossing file system boundaries when
archiving. Use in conjunction with any write operation.
@end table
To avoid operating on files whose names match a particular pattern,
-use the @samp{+exclude=@var{pattern}} or
-@samp{+exclude-from=@var{file}} options.
+use the @samp{--exclude=@var{pattern}} or
+@samp{--exclude-from=@var{file}} options.
-When you specify the @samp{+exclude=@var{pattern}} option, @code{tar}
+When you specify the @samp{--exclude=@var{pattern}} option, @code{tar}
ignores files which match the @var{pattern}, which can be a single
file name or a more complex expression. Thus, if you invoke
-@code{tar} with @samp{tar +create +exclude=*.o}, no files whose names
+@code{tar} with @samp{tar --create --exclude=*.o}, no files whose names
end in @file{.o} are included in the archive.
@c <<< what other things can you use besides "*"?
-@samp{+exclude-from=@var{file}} acts like @samp{+exclude}, but
+@samp{--exclude-from=@var{file}} acts like @samp{--exclude}, but
specifies a file @var{file} containing a list of patterns. @code{tar}
ignores files with names that fit any of these patterns.
You can use either option more than once in a single command.
@table @samp
-@item +exclude=@var{pattern}
+@item --exclude=@var{pattern}
Causes @code{tar} to ignore files that match the @var{pattern}.
-@item +exclude-from=@var{file}
+@item --exclude-from=@var{file}
Causes @code{tar} to ignore files that match the patterns listed in
@var{file}.
@end table
-@c +exclude-from used to be "+exclude", +exclude didn't used to exist.
+@c --exclude-from used to be "--exclude", --exclude didn't used to exist.
To operate only on files with modification or status-change times
-after a particular date, use @samp{+after-date=@var{date}}. You can
-use this option with @samp{tar +create} or @samp{tar +add-file} to
-insure only new files are archived, or with @samp{tar +extract} to
+after a particular date, use @samp{--after-date=@var{date}}. You can
+use this option with @samp{tar --create} or @samp{tar --add-file} to
+insure only new files are archived, or with @samp{tar --extract} to
insure only recent files are resurrected. @refill
-@c +after-date @var{date} or +newer @var{date}
+@c --after-date @var{date} or --newer @var{date}
-@samp{+newer-mtime=@var{date}} acts like @samp{+after-date=@var{date}},
+@samp{--newer-mtime=@var{date}} acts like @samp{--after-date=@var{date}},
but tests just the modification times of the files, ignoring
status-change times.
-@c <<<need example of +newer-mtime with quoted argument
+@c <<<need example of --newer-mtime with quoted argument
Remember that the entire date argument should be quoted if it contains
any spaces.
-@strong{Please Note:} @samp{+after-date} and @samp{+newer-mtime}
+@strong{Please Note:} @samp{--after-date} and @samp{--newer-mtime}
should not be used for incremental backups. Some files (such as those
in renamed directories) are not selected up properly by these options.
@c xref to incremental backup chapter when node name is decided.
@table @samp
-@item +after-date=@var{date}
-@itemx +newer=@var{date}
+@item --after-date=@var{date}
+@itemx --newer=@var{date}
@itemx -N @var{date}
Acts on files only if their modification or inode-changed times are
later than @var{date}. Use in conjunction with any operation.
-@item +newer-mtime=@var{date}
-Acts like @samp{+after-date}, but only looks at modification times.
+@item --newer-mtime=@var{date}
+Acts like @samp{--after-date}, but only looks at modification times.
@end table
@c <<< following is the getdate date format --- needs to be re-written,
need more information than just an error message in order to solve the
problem. The following options can be helpful diagnostic tools.
-When used with most operations, @samp{+verbose} causes @code{tar} to
+When used with most operations, @samp{--verbose} causes @code{tar} to
print the file names of the files or archive members it is operating
-on. When used with @samp{tar +list}, the verbose option causes
+on. When used with @samp{tar --list}, the verbose option causes
@code{tar} to print out an @samp{ls -l} type listing of the files in
the archive.
Verbose output appears on the standard output except when an archive
-is being written to the standard output (as with @samp{tar +create
-+file=- +verbose}). In that case @code{tar} writes verbose output to
+is being written to the standard output (as with @samp{tar --create
+--file=- --verbose}). In that case @code{tar} writes verbose output to
the standard error stream.
@table @samp
-@item +verbose
+@item --verbose
@itemx -v
Prints the names of files or archive members as they are being
operated on. Can be used in conjunction with any operation. When
-used with @samp{+list}, generates an @samp{ls -l} type listing.
+used with @samp{--list}, generates an @samp{ls -l} type listing.
@end table
To find out where in an archive a message was triggered, use
-@samp{+record-number}. @samp{+record-number} causes @code{tar} to
+@samp{--record-number}. @samp{--record-number} causes @code{tar} to
print, along with every message it produces, the record number within
the archive where the message was triggered.
This option is especially useful when reading damaged archives, since
it helps pinpoint the damaged sections. It can also be used with
-@samp{tar +list} when listing a file-system backup tape, allowing you
+@samp{tar --list} when listing a file-system backup tape, allowing you
to choose among several backup tapes when retrieving a file later, in
favor of the tape where the file appears earliest (closest to the
front of the tape).
@c <<< xref when the node name is set and the backup section written
@table @samp
-@item +record-number
+@item --record-number
@itemx -R
Prints the record number whenever a message is generated by
@code{tar}. Use in conjunction with any operation.
@c rewrite below
To print the version number of the @code{tar} program, use @samp{tar
-+version}. @code{tar} prints the version number to the standard
+--version}. @code{tar} prints the version number to the standard
error. For example:
@example
-tar +version
+tar --version
@end example
@noindent
may want to exclude some files and archive members from the operation
(for instance if disk or storage space is tight). You can do this by
excluding certain files automatically (@pxref{File Exclusion}), or by
-performing an operation interactively, using the @samp{+interactive}
+performing an operation interactively, using the @samp{--interactive}
operation.
-When the @samp{+interactive} option is specified, @code{tar} asks for
+When the @samp{--interactive} option is specified, @code{tar} asks for
confirmation before reading, writing, or deleting each file it
encounters while carrying out an operation. To confirm the action you
must type a line of input beginning with @samp{y}. If your input line
<<< this aborts if you won't OK the working directory. this is a bug. -ringo
@table @samp
-@item +interactive
-@itemx +confirmation
+@item --interactive
+@itemx --confirmation
@itemx -w
Asks for confirmation before reading, writing or deleting an archive
member (when listing, comparing or writing an archive or deleting
* Backup Levels:: Levels of backups
* Backup Scripts:: Using scripts to perform backups
and restoration
-* incremental and listed-incremental:: The +incremental
- and +listed-incremental Options
+* incremental and listed-incremental:: The --incremental
+ and --listed-incremental Options
* Problems:: Some common problems and their solutions
@end menu
where ##### are the file systems to restore from, and
##### is a regular expression which specifies which files to
-restore. If you specify +all, the script restores all the files
+restore. If you specify --all, the script restores all the files
in the file system.
You should start the restore script with the media containing the
the tape as needed. @xref{Media}, for a discussion of tape
positioning.
-If you specify @samp{+all} as the @var{files} argument, the
+If you specify @samp{--all} as the @var{files} argument, the
@code{restore} script extracts all the files in the archived file
system into the active file system.
@end ignore
@node incremental and listed-incremental, Problems, Backup Scripts, Backups and Restoration
-@section The @code{+incremental} and @code{+listed-incremental} Options
+@section The @code{--incremental} and @code{--listed-incremental} Options
-@samp{+incremental} is used in conjunction with @samp{+create},
-@samp{+extract} or @samp{+list} when backing up and restoring file
+@samp{--incremental} is used in conjunction with @samp{--create},
+@samp{--extract} or @samp{--list} when backing up and restoring file
systems. An archive cannot be extracted or listed with the
-@samp{+incremental} option specified unless it was created with the
+@samp{--incremental} option specified unless it was created with the
option specified. This option should only be used by a script, not by
the user, and is usually disregarded in favor of
-@samp{+listed-incremental}, which is described below.
+@samp{--listed-incremental}, which is described below.
-@samp{+incremental} in conjunction with @samp{+create} causes
+@samp{--incremental} in conjunction with @samp{--create} causes
@code{tar} to write, at the beginning of the archive, an entry for
each of the directories that will be archived. The entry for a
directory includes a list of all the files in the directory at the
archive that may not be readable by non-GNU versions of the @code{tar}
program.
-@samp{+incremental} in conjunction with @samp{+extract} causes
+@samp{--incremental} in conjunction with @samp{--extract} causes
@code{tar} to read the lists of directory contents previously stored
in the archive, @emph{delete} files in the file system that did not
exist in their directories when the archive was created, and then
This behavior is convenient when restoring a damaged file system from
a succession of incremental backups: it restores the entire state of
the file system to that which obtained when the backup was made. If
-@samp{+incremental} isn't specified, the file system will probably
+@samp{--incremental} isn't specified, the file system will probably
fill up with files that shouldn't exist any more.
-@samp{+incremental} in conjunction with @samp{+list}, causes
+@samp{--incremental} in conjunction with @samp{--list}, causes
@code{tar} to print, for each directory in the archive, the list of
files in that directory at the time the archive was created. This
information is put out in a format that is not easy for humans to
file name is terminated by a null character. The last file is followed
by an additional null and a newline to indicate the end of the data.
-@samp{+listed-incremental}=@var{file} acts like @samp{+incremental},
-but when used in conjunction with @samp{+create} will also cause
+@samp{--listed-incremental}=@var{file} acts like @samp{--incremental},
+but when used in conjunction with @samp{--create} will also cause
@code{tar} to use the file @var{file}, which contains information
about the state of the file system at the time of the last backup, to
decide which files to include in the archive being created. That file
failed.
@c <<< new node on how to find an archive? -ringo
-If you use @code{tar +extract} with the
-@samp{+label=@var{archive-name}} option specified, @code{tar} will
+If you use @code{tar --extract} with the
+@samp{--label=@var{archive-name}} option specified, @code{tar} will
read an archive label (the tape head has to be positioned on it) and
print an error if the archive label doesn't match the
@var{archive-name} specified. @var{archive-name} can be any regular
@xref{Archive Label}. @xref{Matching Format Parameters}.
<<< fix cross references
-@code{tar +list +label} will cause @code{tar} to print the label.
+@code{tar --list --label} will cause @code{tar} to print the label.
@c <<< MIB -- program to list all the labels on a tape?
their counterparts already in the archive, or if they do not already
exist in the archive.
-@item +add-archive
+@item --add-archive
Adds copies of an archive or archives to the end of another archive.
-@item +add-file
+@item --add-file
Adds files to the end of the archive.
-@item +append
+@item --append
Adds files to the end of the archive.
-@item +catenate
+@item --catenate
Adds copies of an archive or archives to the end of another archive.
-@item +compare
+@item --compare
Compares files in the archive with their counterparts in the file
system, and reports differences in file size, mode, owner,
modification date and contents.
-@item +concatenate
+@item --concatenate
Adds copies of an archive or archives to the end of another archive.
-@item +create
+@item --create
Creates a new archive.
-@item +delete
+@item --delete
Deletes files from the archive. All versions of the files are deleted.
-@item +diff
+@item --diff
Compares files in the archive with their counterparts in the file
system, and reports differences in file size, mode, owner,
modification date and contents.
-@item +extract
+@item --extract
Reads files from the archive and writes them into the active file
system.
-@item +get
+@item --get
Reads files from the archive and writes them into the active file
system.
-@item +help
+@item --help
Prints a list of @code{tar} operations and options.
-@item +list
+@item --list
Prints a list of the contents of the archive.
-@item +update
+@item --update
Adds files to the end of the archive, but only if they are newer than
their counterparts already in the archive, or if they do not already
exist in the archive.
-@item +version
+@item --version
Prints the version number of the @code{tar} program to the standard
error.
@end table
Options change the way @code{tar} performs an operation.
@table @samp
-@item +absolute-paths
+@item --absolute-paths
WILL BE INPUT WHEN QUESTION IS RESOLVED
-@item +after-date=@var{date}
+@item --after-date=@var{date}
Limit the operation to files changed after the given date.
@xref{File Exclusion}.
-@item +block-size=@var{number}
+@item --block-size=@var{number}
Specify the blocking factor of an archive. @xref{Blocking Factor}.
-@item +compress
+@item --compress
Specify a compressed archive. @xref{Compressed Archives}.
-@item +compress-block.
+@item --compress-block.
Create a whole block sized compressed archive. @xref{Compressed Archives}.
-@item +confirmation
+@item --confirmation
Solicit confirmation for each file. @xref{Interactive Operation}
-<<< +selective should be a synonym.
+<<< --selective should be a synonym.
-@item +dereference
+@item --dereference
Treat a symbolic link as an alternate name for the file the link
points to. @xref{Symbolic Links}.
-@item +directory=@file{directory}
+@item --directory=@file{directory}
Change the working directory. @xref{Changing Working Directory}.
-@item +exclude=@var{pattern}
+@item --exclude=@var{pattern}
Exclude files which match the regular expression @var{pattern}.
@xref{File Exclusion}.
-@item +exclude-from=@file{file}
+@item --exclude-from=@file{file}
Exclude files which match any of the regular expressions listed in
the file @file{file}. @xref{File Exclusion}.
-@item +file=@var{archive-name}
+@item --file=@var{archive-name}
Name the archive. @xref{Archive Name}).
-@item +files-from=@file{file}
+@item --files-from=@file{file}
Read file-name arguments from a file on the file system.
@xref{File Name Lists}.
-@item +ignore-umask
+@item --ignore-umask
Set modes of extracted files to those recorded in the archive.
@xref{File Writing Options}.
-@item +ignore-zeros
+@item --ignore-zeros
Ignore end-of-archive entries. @xref{Archive Reading Options}.
-<<< this should be changed to +ignore-end
+<<< this should be changed to --ignore-end
-@item +listed-incremental=@var{file-name} (-g)
+@item --listed-incremental=@var{file-name} (-g)
Take a file name argument always. If the file doesn't exist, run a level
zero dump, creating the file. If the file exists, uses that file to see
what has changed.
-@item +incremental (-G)
+@item --incremental (-G)
@c <<<look it up>>>
-@item +tape-length=@var{n} (-L)
+@item --tape-length=@var{n} (-L)
@c <<<alternate way of doing multi archive, will go to that length and
@c prompts for new tape, automatically turns on multi-volume. >>>
@c <<< this needs to be written into main body as well -ringo
-@item +info-script=@var{program-file}
+@item --info-script=@var{program-file}
Create a multi-volume archive via a script. @xref{Multi-Volume Archives}.
-@item +interactive
+@item --interactive
Ask for confirmation before performing any operation on a file or
archive member.
-@item +keep-old-files
+@item --keep-old-files
Prevent overwriting during extraction. @xref{File Writing Options}.
-@item +label=@var{archive-label}
+@item --label=@var{archive-label}
Include an archive-label in the archive being created. @xref{Archive
Label}.
-@item +modification-time
+@item --modification-time
Set the modification time of extracted files to the time they were
extracted. @xref{File Writing Options}.
-@item +multi-volume
+@item --multi-volume
Specify a multi-volume archive. @xref{Multi-Volume Archives}.
-@item +newer=@var{date}
+@item --newer=@var{date}
Limit the operation to files changed after the given date.
@xref{File Exclusion}.
-@item +newer-mtime=@var{date}
+@item --newer-mtime=@var{date}
Limit the operation to files modified after the given date. @xref{File
Exclusion}.
-@item +old
+@item --old
Create an old format archive. @xref{Old Style File Information}.
@c <<< did we agree this should go away as a synonym?
-@item +old-archive
+@item --old-archive
Create an old format archive. @xref{Old Style File Information}.
-@item +one-file-system
+@item --one-file-system
Prevent @code{tar} from crossing file system boundaries when
archiving. @xref{File Exclusion}.
-@item +portable
+@item --portable
Create an old format archive. @xref{Old Style File Information}.
@c <<< was portability, may still need to be changed
-@item +preserve-order
+@item --preserve-order
Help process large lists of file-names on machines with small amounts of
memory. @xref{Archive Reading Options}.
-@item +preserve-permission
+@item --preserve-permission
Set modes of extracted files to those recorded in the archive.
@xref{File Writing Options}.
-@item +read-full-blocks
+@item --read-full-blocks
Read an archive with a smaller than specified block size or which
contains incomplete blocks. @xref{Archive Reading Options}).
-@c should be +partial-blocks (!!!)
+@c should be --partial-blocks (!!!)
-@item +record-number
+@item --record-number
Print the record number where a message is generated.
@xref{Additional Information}.
-@item +same-order
+@item --same-order
Help process large lists of file-names on machines with small amounts of
memory. @xref{Archive Reading Options}.
-@item +same-permission
+@item --same-permission
Set the modes of extracted files to those recorded in the archive.
@xref{File Writing Options}.
-@item +sparse
+@item --sparse
Archive sparse files sparsely. @xref{Sparse Files}.
-@item +starting-file=@var{file-name}
+@item --starting-file=@var{file-name}
Begin reading in the middle of an archive. @xref{Scarce Disk Space}.
-@item +to-stdout
+@item --to-stdout
Write files to the standard output. @xref{File Writing Options}.
-@item +uncompress
+@item --uncompress
Specifdo a compressed archive. @xref{Compressed Archives}.
@item -V @var{archive-label}
Include an archive-label in the archive being created. @xref{Archive
Label}.
-@c was +volume
+@c was --volume
-@item +verbose
+@item --verbose
Print the names of files or archive members as they are being
operated on. @xref{Additional Information}.
-@item +verify
+@item --verify
Check for discrepancies in the archive immediately after it is
written. @xref{Write Verification}.
on. @xref{Additional Information}.
@item -w
-@c <<<see +interactive. WILL BE INPUT WHEN QUESTIONS ARE RESOLVED.>>>
+@c <<<see --interactive. WILL BE INPUT WHEN QUESTIONS ARE RESOLVED.>>>
@item -z
Specify a compressed archive. @xref{Compressed Archives}.
Records may be grouped into @dfn{blocks} for I/O operations. A block
of records is written with a single @code{write()} operation. The
-number of records in a block is specified using the @samp{+block-size}
+number of records in a block is specified using the @samp{--block-size}
option. @xref{Blocking Factor}, for more information about specifying
block size.
@item LF_DUMPDIR
@itemx 'D'
Indicates a directory and a list of files created by the
-@samp{+incremental} option. The @code{size} field gives the total
+@samp{--incremental} option. The @code{size} field gives the total
size of the associated list of files. Each file name is preceded by
either a @code{'Y'} (the file should be in this archive) or an
@code{'N'} (the file is a directory, or is not stored in the archive).
@item LF_VOLHDR
@itemx 'V'
-Marks an archive label that was created using the @samp{+label} option
+Marks an archive label that was created using the @samp{--label} option
when the archive was created (@pxref{Archive Label}. The @code{name}
field contains the argument to the option. The @code{size} field is
zero. Only the first file in each volume of an archive should have
projects / chaz / tar / blobdiff