From fb0a0aaf529180f0415db374500aadb1861e9b26 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sun, 11 Dec 2005 14:10:53 +0000 Subject: [PATCH] Document --delay-directory-restore option. (Configuring Help Summary): Document usage of ARGP_HELP_FMT variable to customize help output. --- doc/tar.texi | 312 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 311 insertions(+), 1 deletion(-) diff --git a/doc/tar.texi b/doc/tar.texi index b899260..2e3b9a4 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -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 -- 2.45.2