[patch] adds missing options and tweaks some sentences

tar.1--fixes-and-update.patch (text/plain), 12.97 KB, created by Benno Schulenberg on 2007-05-08 17:48:50 UTC

--- tar.1.orig	2006-04-22 00:35:21.000000000 +0200
+++ tar.1	2007-05-08 19:39:19.000000000 +0200
@@ -1,4 +1,4 @@
-.TH TAR 1 "Oct 2004" "GNU" "tar"
+.TH TAR 1 "May 2007" "GNU" "tar"
 .SH NAME
 tar \- The GNU version of the tar archiving utility
 .SH SYNOPSIS
@@ -20,7 +20,7 @@
 .I Common Options:
 .nf
 .BR -C ", " --directory " DIR"
-.BR -f ", " --file " F"
+.BR -f ", " --file " FILE"
 .BR -j ", " --bzip2
 .BR -p ", " --preserve-permissions
 .BR -v ", " --verbose
@@ -48,16 +48,25 @@
 .BR -C ", " --directory " DIR"
 ]
 [
-.BR --check-links
+.BR --checkpoint
 ]
 [
-.BR --checkpoint
+.BR --delay-directory-restore
+]
+[
+.BR --exclude " PATTERN"
+]
+[
+.BR --exclude-caches
+]
+[
+.BR --exclude-tag " FILE"
 ]
 [
-.BR -f ", " --file " [HOSTNAME:]F"
+.BR -f ", " --file " [HOSTNAME:]FILE"
 ]
 [
-.BR -F ", " --info-script " F, " --new-volume-script " F"
+.BR -F ", " --info-script " FILE, " --new-volume-script " FILE"
 ]
 [
 .BR --force-local
@@ -66,7 +75,7 @@
 .BR --format " FORMAT"
 ]
 [
-.BR -g ", " --listed-incremental " F"
+.BR -g ", " --listed-incremental " SNAPSHOT"
 ]
 [
 .BR -G ", " --incremental
@@ -87,6 +96,9 @@
 .BR --ignore-case
 ]
 [
+.BR --ignore-command-error
+]
+[
 .BR --ignore-failed-read
 ]
 [
@@ -105,7 +117,7 @@
 .BR --keep-newer-files
 ]
 [
-.BR -l ", " --one-file-system
+.BR -l ", " --check-links
 ]
 [
 .BR -L ", " --tape-length " N"
@@ -120,6 +132,9 @@
 .BR --mode " PERMISSIONS"
 ]
 [
+.BR --mtime " DATE"
+]
+[
 .BR -N ", " --after-date " DATE, " --newer " DATE"
 ]
 [
@@ -129,15 +144,30 @@
 .BR --no-anchored
 ]
 [
+.BR --no-delay-directory-restore
+]
+[
 .BR --no-ignore-case
 ]
 [
+.BR --no-ignore-command-error
+]
+[
+.BR --no-overwrite-dir
+]
+[
+.BR --no-quote-chars
+]
+[
 .BR --no-recursion
 ]
 [
 .BR --no-same-permissions
 ]
 [
+.BR --no-unquote
+]
+[
 .BR --no-wildcards
 ]
 [
@@ -159,6 +189,9 @@
 .BR --occurrence " NUM"
 ]
 [
+.BR --one-file-system
+]
+[
 .BR --overwrite
 ]
 [
@@ -183,6 +216,12 @@
 .BR --preserve
 ]
 [
+.BR --quote-chars " STRING"
+]
+[
+.BR --quote-style " STYLE"
+]
+[
 .BR -R ", " --block-number
 ]
 [
@@ -198,6 +237,9 @@
 .BR --remove-files
 ]
 [
+.BR --restrict
+]
+[
 .BR --rmt-command " CMD"
 ]
 [
@@ -219,7 +261,10 @@
 .BR --show-omitted-dirs
 ]
 [
-.BR --strip-components " NUMBER, " --strip-path " NUMBER (1)"
+.BR --show-transformed-names ", " --show-stored-names
+]
+[
+.BR --strip-components " NUMBER"
 ]
 [
 .BR --suffix " SUFFIX"
@@ -228,12 +273,24 @@
 .BR -T ", " --files-from " FILE"
 ]
 [
-.BR --totals	
+.BR --test-label
+]
+[
+.BR --to-command " COMMAND"
+]
+[
+.BR --totals
+]
+[
+.BR --transform " EXPRESSION"
 ]
 [
 .BR -U ", " --unlink-first
 ]
 [
+.BR --unquote
+]
+[
 .BR --use-compress-program " PROG"
 ]
 [
@@ -264,22 +321,17 @@
 .BR --wildcards-match-slash
 ]
 [
-.BR --exclude " PATTERN"
-]
-[
 .BR -X ", " --exclude-from " FILE"
 ]
 [
-.BR -Z ", " --compress ", " --uncompress
+.BR -z ", " --gzip ", " --gunzip ", " --ungzip
 ]
 [
-.BR -z ", " --gzip ", " --gunzip ", " --ungzip
+.BR -Z ", " --compress ", " --uncompress
 ]
 [
 .BR -[0-7][lmh]
 ]
-
-(1) tar-1.14 uses --strip-path, tar-1.14.90+ uses --strip-components
 .SH DESCRIPTION
 This manual page documents the GNU version of \fBtar\fR, an archiving 
 program designed to store and extract files from an archive file known 
@@ -306,6 +358,10 @@
 .TP
 .B tar -xzf foo.tar.gz blah.txt
 extract the file blah.txt from foo.tar.gz
+.P
+Note: When extracting an archive, specifying -j or -z is not necessary, as
+\fBtar\fR will automatically detect the file type and apply the required
+filter.
 .SH "FUNCTION LETTERS"
 .TP
 .B One of the following options must be used:
@@ -332,17 +388,17 @@
 extract files from an archive
 .TP
 .BR --delete
-delete from the archive (not for use on mag tapes!)
+delete from the archive (not for use on magnetic tapes!)
 .SH "COMMON OPTIONS"
 .TP
 .BR -C ", " --directory " DIR"
 change to directory DIR
 .TP
-.BR -f ", " --file " [HOSTNAME:]F"
-use archive file or device F (default "-", meaning stdin/stdout)
+.BR -f ", " --file " [HOSTNAME:]FILE"
+use archive file or device FILE (default is "-", meaning stdin/stdout)
 .TP
 .BR -j ", " --bzip2
-filter archive through bzip2, use to decompress .bz2 files
+filter archive through bzip2; use to decompress .bz2 files
 .TP
 .BR -p ", " --preserve-permissions
 extract all protection information
@@ -355,7 +411,7 @@
 .SH "ALL OPTIONS"
 .TP
 .BR --atime-preserve
-don't change access times on dumped files
+don't change access times of files that are archived
 .TP
 .BR -b ", " --blocking-factor " N"
 block size of Nx512 bytes (default N=20)
@@ -373,24 +429,33 @@
 .BR -C ", " --directory " DIR"
 change to directory DIR
 .TP
-.BR --check-links
-warn if number of hard links to the file on the filesystem mismatch the 
-number of links recorded in the archive
-.TP
 .BR --checkpoint
 print directory names while reading the archive
 .TP
-.BR -f ", " --file " [HOSTNAME:]F"
-use archive file or device F (default "-", meaning stdin/stdout)
+.BR --delay-directory-restore
+delay setting modification times and permissions of extracted directories
+until the end of extraction
+.TP
+.BR --exclude " PATTERN"
+exclude files based upon PATTERN
+.TP
+.BR --exclude-caches
+exclude directories that contain a cache directory tag
+.TP
+.BR --exclude-tag " FILE"
+exclude directories that contain a file named FILE
+.TP
+.BR -f ", " --file " [HOSTNAME:]FILE"
+use archive file or device FILE (default is "-", meaning stdin/stdout)
 .TP
 .BR -F ", " --info-script " FILE, " --new-volume-script " FILE"
 run script at end of each tape (implies \fI--multi-volume\fR)
 .TP
 .BR --force-local
-archive file is local even if has a colon
+archive file is local even if its name contains a colon
 .TP
 .BR --format " FORMAT"
-selects output archive format
+selects the format of the created archive
 .nf
 \fIv7\fR - Unix V7
 \fIoldgnu\fR - GNU tar <=1.12
@@ -399,14 +464,18 @@
 \fIposix\fR - POSIX.1-2001
 .fi
 .TP
-.BR -g ", " --listed-incremental " F"
+.BR -g ", " --listed-incremental " SNAPSHOT"
 create/list/extract new GNU-format incremental backup
 .TP
+.BR --group " GROUP"
+give files added to the archive a group id of GROUP instead of the group id
+of the source file; this option does not affect extraction
+.TP
 .BR -G ", " --incremental
 create/list/extract old GNU-format incremental backup
 .TP
 .BR -h ", " --dereference
-don't dump symlinks; dump the files they point to
+don't archive symlinks; archive the files they point to
 .TP
 .BR --help
 like this manpage, but not as cool
@@ -417,6 +486,9 @@
 .BR --ignore-case
 ignore case when excluding files
 .TP
+.BR --ignore-command-error
+ignore exit codes of subprocesses
+.TP
 .BR --ignore-failed-read
 don't exit with non-zero status on unreadable files
 .TP
@@ -430,13 +502,14 @@
 keep existing files; don't overwrite them from archive
 .TP
 .BR -K ", " --starting-file " FILE"
-begin at file F in the archive
+begin at file FILE in the archive
 .TP
 .BR --keep-newer-files
 do not overwrite files which are newer than the archive
 .TP
-.BR -l ", " --one-file-system
-stay in local file system when creating an archive
+.BR -l ", " --check-links
+warn if the number of hard links to the file on the filesystem mismatches
+the number of links recorded in the archive
 .TP
 .BR -L ", " --tape-length " N"
 change tapes after writing N*1024 bytes
@@ -450,9 +523,13 @@
 .BR --mode " PERMISSIONS"
 apply PERMISSIONS while adding files (see \fBchmod\fR(1))
 .TP
+.BR --mtime " DATE"
+when creating archives, use  DATE as the modification time of the members,
+instead of their actual modification times
+.TP
 .BR -N ", " --after-date " DATE, " --newer " DATE"
 only store files that were modified or had status updates (permissions,
-ACLs, extended attributes,...) since DATE
+ACLs, extended attributes, ...) since DATE
 .TP
 .BR --newer-mtime " DATE"
 like \fI--newer\fR, but only store files that were modified since DATE
@@ -460,15 +537,34 @@
 .BR --no-anchored
 match any subsequenceof the name's components with \fI--exclude\fR
 .TP
+.BR --no-delay-directory-restore
+modification times and permissions of extracted directories are set when
+all files from this directory have been extracted; this is the default
+.TP
+.BR --no-ignore-command-error
+print warnings about subprocesses that terminated with a non-zero exit code
+.TP
 .BR --no-ignore-case
 use case-sensitive matching with \fI--exclude\fR
 .TP
+.BR --no-overwrite-dir
+preserve metadata of existing directories when extracting files from an
+archive
+.TP
+.BR --no-quote-chars " STRING"
+remove characters listed in STRING from the list of quoted characters
+set by a previous \fI--quote-chars\fR option
+.TP
 .BR --no-recursion
 don't recurse into directories
 .TP
 .BR --no-same-permissions
 apply user's umask when extracting files instead of recorded permissions
 .TP
+.BR --no-unquote
+treat all input file or member names literally, do not interpret
+escape sequences
+.TP
 .BR --no-wildcards
 don't use wildcards with \fI--exclude\fR
 .TP
@@ -496,6 +592,9 @@
 process only NUM occurrences of each named file; used with 
 \fI--delete\fR, \fI--diff\fR, \fI--extract\fR, or \fI--list\fR
 .TP
+.BR --one-file-system
+stay in local file system when creating an archive
+.TP
 .BR --overwrite
 overwrite existing files and directory metadata when extracting
 .TP
@@ -503,9 +602,10 @@
 overwrite directory metadata when extracting
 .TP
 .BR --owner " USER"
-change owner of extraced files to USER
+give files added to the archive a user id of USER instead of the user id
+of the source file; this option does not affect extraction
 .TP
-.BR -p ", " --same-permissions ", " --preserve-permissions
+.BR -p ", " --preserve-permissions ", " --same-permissions
 extract all protection information
 .TP
 .BR -P ", " --absolute-names
@@ -519,7 +619,14 @@
 like \fI--format=posix\fR
 .TP
 .BR --preserve
-like \fI--preserve-permissions\fR \fI--same-order\fR
+like \fI--preserve-permissions\fR plus \fI--same-order\fR
+.TP
+.BR --quote-chars " STRING"
+always quote the characters from STRING, even if the selected quoting
+style would not quote them
+.TP
+.BR --quote-style " STYLE"
+set the quoting style to be used when printing member and file names
 .TP
 .BR -R ", " --record-number
 show record number within archive with each message
@@ -536,6 +643,10 @@
 .BR --remove-files
 remove files after adding them to the archive
 .TP
+.BR --restrict
+disable the use of some potentially harmful options; currently this
+disables shell invocation from the multi-volume menu
+.TP
 .BR --rmt-command " CMD"
 use CMD instead of the default /usr/sbin/rmt
 .TP
@@ -557,10 +668,11 @@
 .BR --show-omitted-dirs
 print directories \fBtar\fR skips while operating on an archive
 .TP
-.BR --strip-components " NUMBER, " --strip-path " NUMBER"
-strip NUMBER of leading components from file names before extraction
-
-(1) tar-1.14 uses --strip-path, tar-1.14.90+ uses --strip-components
+.BR --show-transformed-names ", " --show-stored-names
+display file or member names after applying any \fBsed\fR transformations
+.TP
+.BR --strip-components " NUMBER"
+strip NUMBER of leading path components from file names before extraction
 .TP
 .BR --suffix " SUFFIX"
 use SUFFIX instead of default '~' when backing up files
@@ -568,14 +680,29 @@
 .BR -T ", " --files-from " FILE"
 get names to extract or create from file FILE
 .TP
+.BR --test-label
+read the volume label; if an argument is specified, test whether it
+matches the volume label
+.TP
+.BR --to-command " COMMAND"
+during extraction, pipe extracted files to the standard input of COMMAND
+.TP
 .BR --totals
 print total bytes written with --create
 .TP
+.BR --transform " EXPRESSION"
+transform file or member names using the \fBsed\fR replacement expression
+EXPRESSION
+.TP
 .BR -U ", " --unlink-first
 remove existing files before extracting files of the same name
 .TP
+.BR --unquote
+enable unquoting input file or member names; this is the default
+.TP
 .BR --use-compress-program " PROG"
-access the archive through PROG which is generally a compression program
+access the archive through PROG (which is generally a compression program;
+it must accept option \fI-d\fR)
 .TP
 .BR --utc
 display file modification dates in UTC
@@ -605,20 +732,14 @@
 .BR --wildcards-match-slash
 wildcards match slashes (/) with \fI--exclude\fR
 .TP
-.BR --exclude " PATTERN"
-exclude files based upon PATTERN
-.TP
 .BR -X ", " --exclude-from " FILE"
 exclude files listed in FILE
 .TP
-.BR -Z ", " --compress ", " --uncompress
-filter the archive through compress
-.TP
 .BR -z ", " --gzip ", " --gunzip ", " --ungzip
 filter the archive through gzip
 .TP
-.BR --use-compress-program " PROG"
-filter the archive through PROG (which must accept -d)
+.BR -Z ", " --compress ", " --uncompress
+filter the archive through compress
 .TP
 .BR -[0-7][lmh]
 specify drive and density
@@ -627,7 +748,7 @@
 The maintainer of \fBtar\fR falls into this category.  Thus this man page may 
 not be complete, nor current, and was included in the Gentoo portage tree 
 because man is a great tool :).  This man page was first taken from Debian 
-Linux and has since been loving updated here.
+Linux and has since been lovingly updated here.
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/
 .SH "AUTHORS"