From: Sergey Poznyakoff Date: Fri, 18 Mar 2016 12:27:27 +0000 (+0200) Subject: Revise docs X-Git-Tag: release_1_29~14 X-Git-Url: https://git.gag.com/?a=commitdiff_plain;h=6ac0dd1d73b6f4e36e391d2c6c9f0dd55f6cb766;p=debian%2Ftar Revise docs --- diff --git a/doc/tar.texi b/doc/tar.texi index 87af540c..0d537cca 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -1049,7 +1049,6 @@ all operations and option available for the current version of @node create @section How to Create Archives -@UNREVISED @cindex Creation of the archive @cindex Archive, creation of @@ -1130,10 +1129,27 @@ $ @kbd{tar --create --file=collection.tar blues folk jazz} @end smallexample The order of the arguments is not very important, @emph{when using long -option forms}. You could also say: +option forms}, however you should always remember to use option as the +first argument to tar. For example, the following is wrong: + +@smallexample +$ @kbd{tar blues -c folk -f collection.tar jazz} +tar: -c: Invalid blocking factor +Try 'tar --help' or 'tar --usage' for more information. +@end smallexample + +The error message is produced because @command{tar} always treats its +first argument as an option (or cluster of options), even if it does +not start with dash. This is @dfn{traditional} or @dfn{old option} +style, called so because all implementations of @command{tar} have +used it since the very inception of the tar archiver in 1970s. This +option style will be explained later (@pxref{Old Options}), for now +just remember to always place option as the first argument. + +That being said, you could issue the following command: @smallexample -$ @kbd{tar blues --create folk --file=collection.tar jazz} +$ @kbd{tar --create folk blues --file=collection.tar jazz} @end smallexample @noindent @@ -1272,15 +1288,14 @@ you how an example we showed previously would look using short forms. This example, @smallexample -$ @kbd{tar blues --create folk --file=collection.tar jazz} +$ @kbd{tar --create folk blues --file=collection.tar jazz} @end smallexample @noindent -is confusing as it is. When shown using short forms, however, it -becomes much more so: +is confusing as it is. It becomes even more so when using short forms: @smallexample -$ @kbd{tar blues -c folk -f collection.tar jazz} +$ @kbd{tar -c folk blues -f collection.tar jazz} @end smallexample @noindent @@ -1378,7 +1393,8 @@ Frequently, you will find yourself wanting to determine exactly what a particular archive contains. You can use the @option{--list} (@option{-t}) operation to get the member names as they currently appear in the archive, as well as various attributes of the files at -the time they were archived. For example, you can examine the archive +the time they were archived. For example, assuming @file{practice} is +your working directory, you can examine the archive @file{collection.tar} that you created in the last section with the command, @@ -1395,20 +1411,23 @@ folk jazz @end smallexample -@noindent -The archive @file{bfiles.tar} would list as follows: - -@smallexample -./birds -baboon -./box -@end smallexample - @noindent Be sure to use a @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option just as with @option{--create} (@option{-c}) to specify the name of the archive. +@cindex File name arguments, using @option{--list} with +@xopindex{list, using with file name arguments} +You can specify one or more individual member names as arguments when +using @samp{list}. In this case, @command{tar} will only list the +names of members you identify. For example, @w{@kbd{tar --list +--file=collection.tar folk}} would only print @file{folk}: + +@smallexample +$ @kbd{tar --list --file=collection.tar folk} +folk +@end smallexample + @xopindex{list, using with @option{--verbose}} @xopindex{verbose, using with @option{--list}} If you use the @option{--verbose} (@option{-v}) option with @@ -1434,19 +1453,23 @@ prefixes from file names before storing them in the archive (@xref{absolute}, for more information). In other words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating an archive and @dfn{member names} when listing it. Consider this -example: +example, run from your home directory: @smallexample @group -$ @kbd{tar --create --verbose --file archive /etc/mail} +$ @kbd{tar --create --verbose --file practice.tar ~/practice} tar: Removing leading '/' from member names -/etc/mail/ -/etc/mail/sendmail.cf -/etc/mail/aliases -$ @kbd{tar --test --file archive} -etc/mail/ -etc/mail/sendmail.cf -etc/mail/aliases +/home/myself/practice/ +/home/myself/practice/blues +/home/myself/practice/folk +/home/myself/practice/jazz +/home/myself/practice/collection.tar +$ @kbd{tar --test --file practice.tar} +home/myself/practice/ +home/myself/practice/blues +home/myself/practice/folk +home/myself/practice/jazz +home/myself/practice/collection.tar @end group @end smallexample @@ -1460,35 +1483,53 @@ etc/mail/aliases Print member (as opposed to @emph{file}) names when creating the archive. @end table -@cindex File name arguments, using @option{--list} with -@xopindex{list, using with file name arguments} -You can specify one or more individual member names as arguments when -using @samp{list}. In this case, @command{tar} will only list the -names of members you identify. For example, @w{@kbd{tar --list ---file=afiles.tar apple}} would only print @file{apple}. +With this option, both commands produce the same output: + +@smallexample +@group +$ @kbd{tar --create --verbose --show-stored-names \ + --file practice.tar ~/practice} +tar: Removing leading '/' from member names +home/myself/practice/ +home/myself/practice/blues +home/myself/practice/folk +home/myself/practice/jazz +home/myself/practice/collection.tar +$ @kbd{tar --test --file practice.tar} +home/myself/practice/ +home/myself/practice/blues +home/myself/practice/folk +home/myself/practice/jazz +home/myself/practice/collection.tar +@end group +@end smallexample + +Since @command{tar} preserves file names, those you wish to list must be +specified as they appear in the archive (i.e., relative to the +directory from which the archive was created). Continuing the example +above: + +@smallexample +@group +$ @kbd{tar --list --file=practice.tar folk} +tar: folk: Not found in archive +tar: Exiting with failure status due to previous errors +@end group +@end smallexample -Because @command{tar} preserves file names, these must be specified as -they appear in the archive (i.e., relative to the directory from which -the archive was created). Therefore, it is essential when specifying -member names to @command{tar} that you give the exact member names. -For example, @w{@kbd{tar --list --file=bfiles.tar birds}} would produce an -error message something like @samp{tar: birds: Not found in archive}, -because there is no member named @file{birds}, only one named -@file{./birds}. While the names @file{birds} and @file{./birds} name -the same file, @emph{member} names by default are compared verbatim. +the error message is produced because there is no member named +@file{folk}, only one named @file{home/myself/folk}. -However, @w{@kbd{tar --list --file=bfiles.tar baboon}} would respond -with @file{baboon}, because this exact member name is in the archive file -@file{bfiles.tar}. If you are not sure of the exact file name, -use @dfn{globbing patterns}, for example: +If you are not sure of the exact file name, use @dfn{globbing +patterns}, for example: @smallexample -$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'} +$ @kbd{tar --list --file=practice.tar --wildcards '*/folk'} +home/myself/practice/folk @end smallexample @noindent -will list all members whose name contains @samp{b}. @xref{wildcards}, -for a detailed discussion of globbing patterns and related +@xref{wildcards}, for a detailed discussion of globbing patterns and related @command{tar} command line options. @menu @@ -1567,9 +1608,9 @@ $ @kbd{tar -xvf collection.tar} produces this: @smallexample --rw-r--r-- me/user 28 1996-10-18 16:31 jazz --rw-r--r-- me/user 21 1996-09-23 16:44 blues --rw-r--r-- me/user 20 1996-09-23 16:44 folk +-rw-r--r-- myself/user 28 1996-10-18 16:31 jazz +-rw-r--r-- myself/user 21 1996-09-23 16:44 blues +-rw-r--r-- myself/user 20 1996-09-23 16:44 folk @end smallexample @node extracting files @@ -1612,26 +1653,7 @@ extracted @samp{blues}. You can confirm this by running @command{tar} with @option{--list} (@option{-t}). Remember that as with other operations, specifying the exact member -name is important. @w{@kbd{tar --extract --file=bfiles.tar birds}} -will fail, because there is no member named @file{birds}. To extract -the member named @file{./birds}, you must specify @w{@kbd{tar ---extract --file=bfiles.tar ./birds}}. If you don't remember the -exact member names, use @option{--list} (@option{-t}) option -(@pxref{list}). You can also extract those members that match a -specific @dfn{globbing pattern}. For example, to extract from -@file{bfiles.tar} all files that begin with @samp{b}, no matter their -directory prefix, you could type: - -@smallexample -$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'} -@end smallexample - -@noindent -Here, @option{--wildcards} instructs @command{tar} to treat -command line arguments as globbing patterns and @option{--no-anchored} -informs it that the patterns apply to member names after any @samp{/} -delimiter. The use of globbing patterns is discussed in detail in -@xref{wildcards}. +name is important (@xref{failing commands}, for more examples). You can extract a file to standard output by combining the above options with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard @@ -1746,9 +1768,6 @@ practice/folk practice/jazz @end smallexample -@FIXME{make sure the above works when going through the examples in -order...} - @noindent Likewise, if you try to use this command, @@ -1764,7 +1783,24 @@ to extract the files from the archive. If you have forgotten the correct names of the files in the archive, use @w{@kbd{tar --list --verbose}} to list them correctly. -@FIXME{more examples, here? hag thinks it's a good idea.} +To extract the member named @file{practice/folk}, you must specify + +@smallexample +$ @kbd{tar --extract --file=music.tar practice/folk} +@end smallexample + +@noindent +Notice also, that as explained above, the @file{practice} directory +will be created, if it didn't already exist. There are options that +allow you to strip away a certain number of leading directory +components (@pxref{transform}). For example, + +@smallexample +$ @kbd{tar --extract --file=music.tar --strip-components=1 folk} +@end smallexample + +@noindent +will extract the file @file{folk} into the current working directory. @node going further @section Going Further Ahead in this Manual @@ -3473,6 +3509,8 @@ tar --extract --file archive.tar --strip-components=2 @noindent would extract this file to file @file{name}. +@xref{transform}. + @opsummary{suffix} @item --suffix=@var{suffix}