mirrors/tar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document --delay-directory-restore option.

Browse Source 
(Configuring Help Summary): Document usage of ARGP_HELP_FMT
variable to customize help output.
This commit is contained in:
Sergey Poznyakoff
2005-12-11 14:10:53 +00:00
parent d102bc35a5
commit fb0a0aaf52
1 changed files with 311 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

312
doc/tar.texi
View File

@@ -97,6 +97,7 @@ document. The rest of the menu lists all the lower level nodes.
Appendices
* Changes::
* Configuring Help Summary::
* Genfile::
* Snapshot Files::
* Free Software Needs Free Documentation::
@@ -1311,7 +1312,7 @@ etc/mail/aliases
@table @option
@item --show-stored-names
Print member (not @emph{file}) names when creating the archive.
Print member (as opposed to @emph{file}) names when creating the archive.
@end table
@cindex File name arguments, using @option{--list} with
@@ -2303,6 +2304,12 @@ while saving space. @xref{gzip}.
(See @option{--interactive}.) @xref{interactive}.
@opindex delay-directory-restore, summary
@item --delay-directory-restore
Delay setting modification times and permissions of extracted
directories until the end of extraction. @xref{Directory Modification Times and Permissions}.
@opindex dereference, summary
@item --dereference
@itemx -h
@@ -2567,6 +2574,13 @@ also back up files for which any status information has changed).
An exclude pattern can match any subsequence of the name's components.
@xref{controlling pattern-matching with exclude}.
@opindex no-delay-directory-restore, summary
@item --no-delay-directory-restore
Setting modification times and permissions of extracted
directories when all files from this directory has been
extracted. This is the default. @xref{Directory Modification Times and Permissions}.
@opindex no-ignore-case, summary
@item --no-ignore-case
Use case-sensitive matching when excluding files.
@@ -3332,6 +3346,9 @@ for getting only the pertinent lines. Notice, however, that some
@command{tar} options have long description lines and the above
command will list only the first of them.
The exact look of the option summary displayed by @kbd{tar --help} is
configurable. @xref{Configuring Help Summary}, for a detailed description.
@opindex usage
If you only wish to check the spelling of an option, running @kbd{tar
--usage} may be a better choice. This will display a terse list of
@@ -4293,6 +4310,7 @@ encountered while reading an archive. Use in conjunction with
* Recursive Unlink::
* Data Modification Times::
* Setting Access Permissions::
* Directory Modification Times and Permissions::
* Writing to Standard Output::
* Writing to an External Program::
* remove files::
@@ -4479,6 +4497,85 @@ archive, instead of current umask settings. Use in conjunction with
@option{--extract} (@option{--get}, @option{-x}).
@end table
@node Directory Modification Times and Permissions
@unnumberedsubsubsec Directory Modification Times and Permissions
After sucessfully extracting a file member, @GNUTAR{} normally
restores its permissions and modification times, as described in the
previous sections. This cannot be done for directories, because
after extracting a directory @command{tar} will almost certainly
extract files into that directory and this will cause the directory
modification time to be updated. Moreover, restoring that directory
permissions may not permit file creation within it. Thus, restoring
directory permissions and modification times must be delayed at least
until all files have been extracted into that directory. @GNUTAR{}
restores directories using the following approach.
The extracted directories are created with the mode specified in the
archive, as modified by the umask of the user, which gives sufficient
permissions to allow file creation. The meta-information about the
directory is recorded in the temporary list of directories. When
preparing to extract next archive member, @GNUTAR{} checks if the
directory prefix of this file contains the remembered directory. If
it does not, the program assumes that all files have been extracted
into that directory, restores its modification time and permissions
and removes its entry from the internal list. This approach allows
to correctly restore directory meta-information in the majority of
cases, while keeping memory requirements sufficiently small. It is
based on the fact, that most @command{tar} archives use the predefined
order of members: first the directory, then all the files and
subdirectories in that directory.
However, this is not always true. The most important exception are
incremental archives (@pxref{Incremental Dumps}). The member order in
an incremental archive is reversed: first all directory members are
stored, followed by other (non-directory) members. So, when extracting
from incremental archives, @GNUTAR{} alters the above procedure. It
remebers all restored directories, and restores their meta-data
only after the entire archive has been processed. Notice, that you do
not need to specity any special options for that, as @GNUTAR{}
automatically detects archives in incremental format.
There may be cases, when such processing is required for normal archives
too. Consider the following example:
@smallexample
@group
$ @kbd{tar --no-recursion -cvf archive \
foo foo/file1 bar bar/file foo/file2}
foo/
foo/file1
bar/
bar/file
foo/file2
@end group
@end smallexample
During the normal operation, after encountering @file{bar}
@GNUTAR{} will assume that all files from the directory @file{foo}
were already extracted and will therefore restore its timestamp and
permission bits. However, after extracting @file{foo/file2} the
directory timestamp will be offset again.
To correctly restore directory meta-information in such cases, use
@option{delay-directory-restore} command line option:
@table @option
@opindex delay-directory-restore
@item --delay-directory-restore
Delays restoring of the modification times and permissions of extracted
directories until the end of extraction. This way, correct
meta-information is restored even if the archive has unusual member
ordering.
@opindex no-delay-directory-restore
@item --no-delay-directory-restore
Cancel the effect of the previous @option{--delay-directory-restore}.
Use this option if you have used @option{--delay-directory-restore} in
@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to
temporarily disable it.
@end table
@node Writing to Standard Output
@unnumberedsubsubsec Writing to Standard Output
@@ -9392,6 +9489,219 @@ These options are deprecated. Please use @option{--format=v7} instead.
This option is deprecated. Please use @option{--format=posix} instead.
@end table
@node Configuring Help Summary
@appendix Configuring Help Summary
Running @kbd{tar --help} displays the short @command{tar} option
summary (@pxref{help}). This summary is organised by @dfn{groups} of
semantically close options. The options within each group are printed
in the following order: a short option, eventually followed by a list
of corresponding long option names, followed by a short description of
the option. For example, here is an excerpt from the actual @kbd{tar
--help} output:
@verbatim
Main operation mode:
-A, --catenate, --concatenate append tar files to an archive
-c, --create create a new archive
-d, --diff, --compare find differences between archive and
file system
--delete delete from the archive
@end verbatim
@vrindex ARGP_HELP_FMT, environment variable
The exact visual representation of the help output is configurable via
@env{ARGP_HELP_FMT} environment variable. The value of this variable
is a comma-separated list of @dfn{format variable} assignments. There
are two kinds of format variables. An @dfn{offset variable} keeps the
offset of some part of help output text from the leftmost column on
the screen. A @dfn{boolean} variable is a flag that toggles some
output feature on or off. Depending on the type of the corresponding
variable, there are two kinds of assignments:
@table @asis
@item Offset assignment
The assignment to an offset variable has the following syntax:
@smallexample
@var{variable}=@var{value}
@end smallexample
@noindent
where @var{variable} is the variable name, and @var{value} is a
numeric value to be assigned to the variable.
@item Boolean assignment
To assign @code{true} value to a variable, simply put this variable name. To
assign @code{false} value, prefix the variable name with @samp{no-}. For
example:
@smallexample
@group
# Assign @code{true} value:
dup-args
# Assign @code{false} value:
no-dup-args
@end group
@end smallexample
@end table
Following variables are declared:
@deftypevr {Help Output} boolean dup-args
If true, arguments for an option are shown with both short and long
options, even when a given option has both forms, for example:
@smallexample
-f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
@end smallexample
If false, then if an option has both short and long forms, the
argument is only shown with the long one, for example:
@smallexample
-f, --file=ARCHIVE use archive file or device ARCHIVE
@end smallexample
@noindent
and a message indicating that the argument is applicable to both
forms is printed below the options. This message can be disabled
using @code{dup-args-note} (see below).
The default is false.
@end deftypevr
@deftypevr {Help Output} boolean dup-args-note
If this variable is true, which is the default, the following notice
is displayed at the end of the help output:
@quotation
Mandatory or optional arguments to long options are also mandatory or
optional for any corresponding short options.
@end quotation
Setting @code{no-dup-args-note} inhibits this message. Normally, only one of
variables @code{dup-args} or @code{dup-args-note} should be set.
@end deftypevr
@deftypevr {Help Output} offset short-opt-col
Column in which short options start. Default is 2.
@smallexample
@group
$ @kbd{tar --help|grep ARCHIVE}
-f, --file=ARCHIVE use archive file or device ARCHIVE
$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE}
-f, --file=ARCHIVE use archive file or device ARCHIVE
@end group
@end smallexample
@end deftypevr
@deftypevr {Help Output} offset long-opt-col
Column in which long options start. Default is 6. For example:
@smallexample
@group
$ @kbd{tar --help|grep ARCHIVE}
-f, --file=ARCHIVE use archive file or device ARCHIVE
$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE}
-f, --file=ARCHIVE use archive file or device ARCHIVE
@end group
@end smallexample
@end deftypevr
@deftypevr {Help Output} offset doc-opt-col
Column in which @dfn{doc options} start. A doc option isn't actually
an option, but rather an arbitrary piece of documentation that is
displayed in much the same manner as the options. For example, in
the description of @option{--format} option:
@smallexample
@group
-H, --format=FORMAT create archive of the given format.
FORMAT is one of the following:
gnu GNU tar 1.13.x format
oldgnu GNU format as per tar <= 1.12
pax POSIX 1003.1-2001 (pax) format
posix same as pax
ustar POSIX 1003.1-1988 (ustar) format
v7 old V7 tar format
@end group
@end smallexample
@noindent
the format names are doc options. Thus, if you set
@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
will look as follows:
@smallexample
@group
-H, --format=FORMAT create archive of the given format.
FORMAT is one of the following:
gnu GNU tar 1.13.x format
oldgnu GNU format as per tar <= 1.12
pax POSIX 1003.1-2001 (pax) format
posix same as pax
ustar POSIX 1003.1-1988 (ustar) format
v7 old V7 tar format
@end group
@end smallexample
@end deftypevr
@deftypevr {Help Output} offset opt-doc-col
Column in which option description starts. Default is 29.
@smallexample
@group
$ @kbd{tar --help|grep ARCHIVE}
-f, --file=ARCHIVE use archive file or device ARCHIVE
$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE}
-f, --file=ARCHIVE use archive file or device ARCHIVE
$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE}
-f, --file=ARCHIVE
use archive file or device ARCHIVE
@end group
@end smallexample
@noindent
Notice, that the description starts on a separate line if
@code{opt-doc-col} value is too small.
@end deftypevr
@deftypevr {Help Output} offset header-col
Column in which @dfn{group headers} are printed. A group header is a
descriptive text preceding an option group. For example, in the
following text:
@verbatim
Main operation mode:
-A, --catenate, --concatenate append tar files to
an archive
-c, --create create a new archive
@end verbatim
@noindent
@samp{Main operation mode:} is the group header.
The default value is 1.
@end deftypevr
@deftypevr {Help Output} offset usage-indent
Indentation of wrapped usage lines. Affects @option{--usage}
output. Default is 12.
@end deftypevr
@deftypevr {Help Output} offset rmargin
Right margin of the text output. Used for wrapping.
@end deftypevr
@node Genfile
@appendix Genfile
@include genfile.texi