update manpage, this thing is sexy

1 files changed, 289 insertions, 140 deletions

diff --git a/app-arch/tar/files/tar.1 b/app-arch/tar/files/tar.1
index a57a42def30b..8b09f982a2c8 100644
--- a/app-arch/tar/files/tar.1
+++ b/app-arch/tar/files/tar.1
@@ -1,10 +1,9 @@
-.\" @(#)tar.1 1.11.1 93/19/22 PJV;
-.TH TAR 1 "22 September 1993"
+.TH TAR 1 "Oct 2004" "GNU" "tar"
 .SH NAME
 tar \- The GNU version of the tar archiving utility
 .SH SYNOPSIS
 .B tar
-.I [operation] [options]
+.I <operation> [options]
 
 .I Operations:
 .nf
@@ -18,28 +17,41 @@ tar \- The GNU version of the tar archiving utility
 .B --delete
 .fi
 
-.I Options:
+.I Common Options:
+.nf
+.B -C, --directory DIR
+.B -f, --file F
+.B -j, --bzip2
+.B -p, --preserve-permissions
+.B -v, --verbose
+.B -z, --gzip
+.fi
+
+.I All Options:
 .br
 [
 .B --atime-preserve
 ]
 [
-.B --backup=BACKUP-TYPE
-]
-[
 .B -b, --blocking-factor N
 ]
 [
 .B -B, --read-full-records
 ]
 [
+.B --backup BACKUP-TYPE
+]
+[
+.B --block-compress
+]
+[
 .B -C, --directory DIR
 ]
 [
 .B --check-links
 ]
 [
-.B --checkpoint	
+.B --checkpoint
 ]
 [
 .B -f, --file [HOSTNAME:]F
@@ -135,6 +147,9 @@ tar \- The GNU version of the tar archiving utility
 .B --null	
 ]
 [
+.B --numeric-owner
+]
+[
 .B -o, --old-archive, --portability, --no-same-owner
 ]
 [
@@ -165,13 +180,13 @@ tar \- The GNU version of the tar archiving utility
 .B --posix
 ]
 [
-.B --preserve	
+.B --preserve
 ]
 [
 .B -R, --block-number
 ]
 [
-.B --record-size
+.B --record-size SIZE
 ]
 [
 .B --recursion
@@ -186,7 +201,7 @@ tar \- The GNU version of the tar archiving utility
 .B --rmt-command CMD
 ]
 [
-.B --rsh-command=CMD
+.B --rsh-command CMD
 ]
 [
 .B -s, --same-order, --preserve-order
@@ -198,16 +213,13 @@ tar \- The GNU version of the tar archiving utility
 .B --same-owner
 ]
 [
-.B --numeric-owner
-]
-[
 .B --show-defaults
 ]
 [
 .B --show-omitted-dirs
 ]
 [
-.B --strip-path NUMBER
+.B --strip-components NUMBER, --strip-path NUMBER (1)
 ]
 [
 .B --suffix SUFFIX
@@ -237,13 +249,13 @@ tar \- The GNU version of the tar archiving utility
 .B --version	
 ]
 [
-.B --volno-file FILE
+.B --volno-file F
 ]
 [
 .B -w, --interactive, --confirmation
 ]
 [
-.B -W, --verify	
+.B -W, --verify
 ]
 [
 .B --wildcards
@@ -261,47 +273,39 @@ tar \- The GNU version of the tar archiving utility
 .B -Z, --compress, --uncompress
 ]
 [
-.B -z, --gzip, --gunzip, --ungzip	
+.B -z, --gzip, --gunzip, --ungzip
 ]
 [
-.B --block-compress
-]
-[
-.B -[0-7][lmh]	
+.B -[0-7][lmh]
 ]
+
+(1) tar-1.14 uses --strip-path, tar-1.14.90+ uses --strip-components
 .SH DESCRIPTION
-.LP
-This manual page documents the GNU version of
-.B tar
-, an archiving program designed to store and extract files from 
-an archive file known as a 
-.IR tarfile.
-A 
-.IR tarfile 
-may be made on a tape drive, however, it is also common
-to write a
-.IR tarfile
-to a normal file. 
-The first argument to 
-.B tar
-must be one of the options:
-.BR Acdrtux ,
-followed by any optional functions.
-The final arguments to 
-.B tar
-are the names of the files or directories which should be archived. The use
-of a directory name always implies that the subdirectories below should be
-included in the archive.
+This manual page documents the GNU version of \fBtar\fR, an archiving 
+program designed to store and extract files from an archive file known 
+as a \fItarfile\fR.  A \fItarfile\fR may be made on a tape drive, 
+however, it is also common to write a \fItarfile\fR to a normal file.  
+The first argument to \fBtar\fR must be one of the options \fBAcdrtux\fR, 
+followed by any optional functions.  The final arguments to \fBtar\fR 
+are the names of the files or directories which should be archived.  The 
+use of a directory name always implies that the subdirectories below 
+should be included in the archive.
 .SH EXAMPLES
 .TP
-.B tar -xvvf foo.tar
-extract foo.tar
+.B tar -xvf foo.tar
+verbosely extract foo.tar
 .TP
-.B tar -xvvzf foo.tar.gz
+.B tar -xzf foo.tar.gz
 extract gzipped foo.tar.gz
 .TP
-.B tar -cvvf foo.tar foo/
-tar contents of folder foo in foo.tar
+.B tar -cjf foo.tar.bz2 bar/
+create bzipped tar archive of the directory foo called foo.tar.bz2
+.TP
+.B tar -xjf foo.tar.bz2 -C bar/
+extract bzipped foo.tar.bz2 after changing directory to bar
+.TP
+.B tar -xzf foo.tar.bz2 blah.txt
+extract the file blah.txt from foo.tar.bz2
 .SH "FUNCTION LETTERS"
 .TP
 .B One of the following options must be used:
@@ -309,181 +313,326 @@ tar contents of folder foo in foo.tar
 .B -A, --catenate, --concatenate
 append tar files to an archive
 .TP
-.B -c, --create	
+.B -c, --create
 create a new archive
 .TP
 .B -d, --diff, --compare
 find differences between archive and file system
 .TP
-.B --delete		
-delete from the archive (not for use on mag tapes!)
-.TP
-.B -r, --append		
+.B -r, --append
 append files to the end of an archive
 .TP
-.B -t, --list		
+.B -t, --list
 list the contents of an archive
 .TP
-.B -u, --update		
-only append files that are newer than copy in archive
+.B -u, --update
+only append files that are newer than the existing in archive
 .TP
-.B -x, --extract, --get		
+.B -x, --extract, --get
 extract files from an archive
-.SH "OTHER OPTIONS"
 .TP
-.B --atime-preserve	
+.B --delete
+delete from the archive (not for use on mag tapes!)
+.SH "COMMON OPTIONS"
+.TP
+.B -C, --directory DIR
+change to directory DIR
+.TP
+.B -f, --file [HOSTNAME:]F
+use archive file or device F (default "-", meaning stdin/stdout)
+.TP
+.B -j, --bzip2
+filter archive through bzip2, use to decompress .bz2 files
+.TP
+.B -p, --preserve-permissions
+extract all protection information
+.TP
+.B -v, --verbose
+verbosely list files processed
+.TP
+.B -z, --gzip, --ungzip
+filter the archive through gzip
+.SH "ALL OPTIONS"
+.TP
+.B --atime-preserve
 don't change access times on dumped files
 .TP
-.B -b, --block-size N	
+.B -b, --blocking-factor N
 block size of Nx512 bytes (default N=20)
 .TP
-.B -B, --read-full-blocks	
+.B -B, --read-full-blocks
 reblock as we read (for reading 4.2BSD pipes)
-.TP 
-.B -C, --directory DIR	
+.TP
+.B --backup BACKUP-TYPE
+backup files instead of deleting them using BACKUP-TYPE simple or 
+numbered
+.TP
+.B --block-compress
+block the output of compression program for tapes
+.TP
+.B -C, --directory DIR
 change to directory DIR
-.TP 
-.B --checkpoint		
+.TP
+.B --check-links
+warn if number of hard links to the file on the filesystem mismatch the 
+number of links recorded in the archive
+.TP
+.B --checkpoint
 print directory names while reading the archive
 .TP
-.B -f, --file [HOSTNAME:]F	
+.B -f, --file [HOSTNAME:]F
 use archive file or device F (default "-", meaning stdin/stdout)
 .TP
-.B --force-local		
+.B -F, --info-script F --new-volume-script F
+run script at end of each tape (implies \fI--multi-volume\fR)
+.TP
+.B --force-local
 archive file is local even if has a colon
-.TP 
-.B -F, --info-script F --new-volume-script F 
-run script at end of each tape (implies -M)
 .TP
-.B -G, --incremental	
-create/list/extract old GNU-format incremental backup
+.B --format FORMAT
+selects output archive format
+.nf
+\fIv7\fR - Unix V7
+\fIoldgnu\fR - GNU tar <=1.12
+\fIgnu\fR - GNU tar 1.13
+\fIustar\fR - POSIX.1-1988
+\fIposix\fR - POSIX.1-2001
+.fi
 .TP
-.B -g, --listed-incremental F 
+.B -g, --listed-incremental F
 create/list/extract new GNU-format incremental backup
-.TP 
-.B -h, --dereference	
+.TP
+.B -G, --incremental
+create/list/extract old GNU-format incremental backup
+.TP
+.B -h, --dereference
 don't dump symlinks; dump the files they point to
 .TP
-.B -i, --ignore-zeros	
+.B --help
+like this manpage, but not as cool
+.TP
+.B -i, --ignore-zeros
 ignore blocks of zeros in archive (normally mean EOF)
 .TP
-.B -j, --bzip2
-filter archive through bzip2, use to decompress .bz2 files
+.B --ignore-case
+ignore case when excluding files
 .TP
-.B --ignore-failed-read	
+.B --ignore-failed-read
 don't exit with non-zero status on unreadable files
 .TP
-.B -k, --keep-old-files	
+.B --index-file FILE
+send verbose output to FILE instead of stdout
+.TP
+.B -j, --bzip2
+filter archive through bzip2, use to decompress .bz2 files
+.TP
+.B -k, --keep-old-files
 keep existing files; don't overwrite them from archive
 .TP
-.B -K, --starting-file F	
+.B -K, --starting-file F
 begin at file F in the archive
 .TP
-.B -l, --one-file-system	
+.B --keep-newer-files
+do not overwrite files which are newer than the archive
+.TP
+.B -l, --one-file-system
 stay in local file system when creating an archive
 .TP
-.B -L, --tape-length N	
+.B -L, --tape-length N
 change tapes after writing N*1024 bytes
 .TP
-.B -m, --modification-time	
+.B -m, --touch, --modification-time
 don't extract file modified time
 .TP
-.B -M, --multi-volume	
+.B -M, --multi-volume
 create/list/extract multi-volume archive
 .TP
-.B -N, --after-date DATE, --newer DATE	
+.B --mode PERMISSIONS
+apply PERMISSIONS while adding files (see \fBchmod\fR(1))
+.TP
+.B -N, --after-date DATE, --newer DATE
 only store files newer than DATE
 .TP
-.B -o, --old-archive, --portability	
-write a V7 format archive, rather than ANSI format
+.B --newer-mtime DATE
+like \fI--newer\fR, but with a DATE
+.TP
+.B --no-anchored
+match any subsequenceof the name's components with \fI--exclude\fR
+.TP
+.B --no-ignore-case
+use case-sensitive matching with \fI--exclude\fR
+.TP
+.B --no-recursion
+don't recurse into directories
+.TP
+.B --no-same-permissions
+apply user's umask when extracting files instead of recorded permissions
+.TP
+.B --no-wildcards
+don't use wildcards with \fI--exclude\fR
+.TP
+.B --no-wildcards-match-slash
+wildcards do not match slashes (/) with \fI--exclude\fR
+.TP
+.B --null
+\fI--files-from\fR reads null-terminated names, disable \fI--directory\fR
+.TP
+.B --numeric-owner
+always use numbers for user/group names
+.TP
+.B -o, --old-archive, --portability
+like \fI--format=v7\fR; \fI-o\fR exhibits this behavior when creating an 
+archive (deprecated behavior)
+.TP
+.B -o, --no-same-owner
+do not attempt to restore ownership when extracting; \fI-o\fR exhibits 
+this behavior when extracting an archive
 .TP
-.B -O, --to-stdout		
+.B -O, --to-stdout
 extract files to standard output
 .TP
-.B -p, --same-permissions, --preserve-permissions 
+.B --occurrence NUM
+process only NUM occurrences of each named file; used with 
+\fI--delete\fR, \fI--diff\fR, \fI--extract\fR, or \fI--list\fR
+.TP
+.B --overwrite
+overwrite existing files and directory metadata when extracting
+.TP
+.B --overwrite-dir
+overwrite directory metadata when extracting
+.TP
+.B --owner USER
+change owner of extraced files to USER
+.TP
+.B -p, --same-permissions, --preserve-permissions
 extract all protection information
 .TP
-.B -P, --absolute-paths	
+.B -P, --absolute-names
 don't strip leading `/'s from file names
 .TP
-.B --preserve		
-like -p -s
+.B --pax-option KEYWORD-LIST
+used only with POSIX.1-2001 archives to modify the way \fBtar\fR handles 
+extended header keywords
 .TP
-.B -R, --record-number	
+.B --posix
+like \fI--format=posix\fR
+.TP
+.B --preserve
+like \fI--preserve-permissions\fR \fI--same-order\fR
+.TP
+.B -R, --record-number
 show record number within archive with each message
-.TP 
-.B --remove-files		
+.TP
+.B --record-size SIZE
+use SIZE bytes per record when accessing archives
+.TP
+.B --recursion
+recurse into directories
+.TP
+.B --recursive-unlink
+remove existing directories before extracting directories of the same name
+.TP
+.B --remove-files
 remove files after adding them to the archive
 .TP
-.B -s, --same-order, --preserve-order	
+.B --rmt-command CMD
+use CMD instead of the default /usr/sbin/rmt
+.TP
+.B --rsh-command CMD
+use remote CMD instead of \fBrsh\fR(1)
+.TP
+.B -s, --same-order, --preserve-order
 list of names to extract is sorted to match archive
 .TP
-.B --same-owner		
+.B -S, --sparse
+handle sparse files efficiently
+.TP
+.B --same-owner
 create extracted files with the same ownership 
 .TP
-.B --numeric-owner
-always use numbers for user/group names
+.B --show-defaults
+display the default options used by \fBtar\fR
 .TP
-.B -S, --sparse		
-handle sparse files efficiently
-.TP 
-.B -T, --files-from F	
-get names to extract or create from file F
+.B --show-omitted-dirs
+print directories \fBtar\fR skips while operating on an archive
+.TP
+.B --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
 .TP
-.B --null			
--T reads null-terminated names, disable -C
+.B --suffix SUFFIX
+use SUFFIX instead of default '~' when backing up files
 .TP
-.B --totals		
+.B -T, --files-from F
+get names to extract or create from file F
+.TP
+.B --totals
 print total bytes written with --create
 .TP
-.B -v, --verbose		
+.B -U, --unlink-first
+remove existing files before extracting files of the same name
+.TP
+.B --use-compress-program PROG
+access the archive through PROG which is generally a compression program
+.TP
+.B --utc
+display file modification dates in UTC
+.TP
+.B -v, --verbose
 verbosely list files processed
 .TP
-.B -V, --label NAME	
+.B -V, --label NAME
 create archive with volume name NAME
-.TP 
-.B --version		
-print tar program version number
 .TP
-.B -w, --interactive, --confirmation	
+.B --version
+print \fBtar\fR program version number
+.TP
+.B --volno-file F
+keep track of which volume of a multi-volume archive its working in 
+FILE; used with \fI--multi-volume\fR
+.TP
+.B -w, --interactive, --confirmation
 ask for confirmation for every action
 .TP
-.B -W, --verify		
+.B -W, --verify
 attempt to verify the archive after writing it
 .TP
-.B --exclude=FILE		
-exclude file FILE
+.B --wildcards
+use wildcards with \fI--exclude\fR
+.TP
+.B --wildcards-match-slash
+wildcards match slashes (/) with \fI--exclude\fR
+.TP
+.B --exclude PATTERN
+exclude files based upon PATTERN
 .TP
-.B -X, --exclude-from FILE	
+.B -X, --exclude-from FILE
 exclude files listed in FILE
 .TP
-.B -Z, --compress, --uncompress      	
+.B -Z, --compress, --uncompress
 filter the archive through compress
-.TP 
-.B -z, --gzip, --ungzip		
+.TP
+.B -z, --gzip, --gunzip, --ungzip
 filter the archive through gzip
 .TP
 .B --use-compress-program PROG
 filter the archive through PROG (which must accept -d)
 .TP
-.B --block-compress	
-block the output of compression program for tapes
-.TP
-.B --rsh-command=CMD
-Use remote COMMAND instead of `rsh'.  This option exists so that
-people who use something other than the standard `rsh' (e.g., a
-Kerberized `rsh') can access a remote device.
-.TP
-.B -[0-7][lmh]		
+.B -[0-7][lmh]
 specify drive and density
 .SH BUGS
-.LP
 The GNU folks, in general, abhor man pages, and create info documents instead.
-The maintainer of tar falls into this category.  This man page is neither
-complete, nor current, and was included in the Debian Linux packaging of tar
-entirely to reduce the frequency with which the lack of a man page gets
-reported as a bug in our defect tracking system.
-
-If you really want to understand tar, then you should run info and read the
-tar info pages, or use the info mode in emacs.
-
+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.
+.SH "REPORTING BUGS"
+Please report bugs via http://bugs.gentoo.org/
+.SH "AUTHORS"
+.nf
+Debian Linux http://www.debian.org/
+Mike Frysinger <vapier@gentoo.org>
+.fi
+.SH "CVS HEADER"
+$Header: /var/cvsroot/gentoo-x86/app-arch/tar/files/tar.1,v 1.3 2004/10/12 15:52:36 vapier Exp $