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