[arch-commits] Commit in tar/trunk (tar.1)

Pierre Schmitz pierre at archlinux.org
Tue Mar 2 13:21:06 EST 2010

    Date: Tuesday, March 2, 2010 @ 13:21:05
  Author: pierre
Revision: 70959

update tar man page from debian package


 tar.1 |  694 ++++++++++++++++++++++++++++++----------------------------------
 1 file changed, 334 insertions(+), 360 deletions(-)

Modified: tar.1
--- tar.1	2010-03-02 17:49:08 UTC (rev 70958)
+++ tar.1	2010-03-02 18:21:05 UTC (rev 70959)
@@ -1,388 +1,362 @@
-.\" @(#)tar.1 1.11.1 93/19/22 PJV;
-.TH TAR 1 "29 Aug 2007"
-tar \- The GNU version of the tar archiving utility
-.B tar
-.B \-
-.B A \-\-catenate \-\-concatenate \||\| c \-\-create \||\| d \-\-diff \-\-compare \||\| \-\-delete \||\| r \-\-append \||\| t \-\-list \||\| u \-\-update \||\| x \-\-extract \-\-get 
-.I [ options ]
-.I pathname [ pathname ... ] 
-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.
-.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.
-.B tar \-xvvf foo.tar
-extract foo.tar
-.B tar \-xvvzf foo.tar.gz
-extract gzipped foo.tar.gz
-.B tar \-cvvf foo.tar foo/
-tar contents of folder foo in foo.tar
-.B One of the following options must be used:
-.B \-A, \-\-catenate, \-\-concatenate
+.\" generated by script on Tue Aug  4 19:50:16 2009
+.Dd Aug  4, 2009
+.Dt TAR 1
+.Nm tar
+.Nd The GNU version of the tar archiving utility
+.Nm tar
+.Oo Fl Oc Cm A Fl \-catenate \-concatenate Cm \||\| c Fl \-create Cm \||\| d Fl \-diff \-compare Cm \||\| Fl \-delete Cm \||\| r Fl \-append Cm \||\| t Fl \-list Cm \||\| Fl \-test\-label Cm \||\| u Fl \-update Cm \||\| x Fl \-extract \-get
+.Op Ar options
+.Op Ar pathname ...
+.Nm Tar
+stores and extracts files from a tape or disk archive.
+The first argument to
+should be a function; either one of the letters
+.Cm Acdrtux ,
+or one of the long function names.
+A function letter need not be prefixed with ``\-'', and may be combined
+with other single-letter options.
+A long function name must be prefixed with
+.Cm \\-\\- .
+Some options take a parameter; with the single-letter form
+these must be given as separate arguments.
+With the long form, they may be given by appending
+.Cm = Ns Ar value
+to the option.
+Main operation mode:
+.Bl -tag -width flag
+.It Fl A , Fl \-catenate , Fl \-concatenate
 append tar files to an archive
-.B \-c, \-\-create	
+.It Fl c , Fl \-create
 create a new archive
-.B \-d, \-\-diff, \-\-compare
+.It Fl d , Fl \-diff , Fl \-compare
 find differences between archive and file system
-.B \-\-delete		
-delete from the archive (not for use on mag tapes!)
-.B \-r, \-\-append		
+.It Fl \-delete
+delete from the archive (not on mag tapes!)
+.It Fl r , Fl \-append
 append files to the end of an archive
-.B \-t, \-\-list		
+.It Fl t , Fl \-list
 list the contents of an archive
-.B \-u, \-\-update		
-only append files that are newer than copy in archive
-.B \-x, \-\-extract, \-\-get		
+.It Fl \-test\-label
+test the archive volume label and exit
+.It Fl u , Fl \-update
+only append files newer than copy in archive
+.It Fl x , Fl \-extract , Fl \-get
 extract files from an archive
-.B \-\-allow\-name\-mangling
-re-enable handling of GNUTYPE_NAMES which is now disabled by default
-.B \-\-anchored	
-force exclusion patterns to match initial subsequences
-.B \-\-atime\-preserve	
-don't change access times on dumped files
-.B \-a, \-\-auto\-compress
-with \-\-create, selects compression algorithm basing on the suffix
-of the archive file name
-.B \-b, \-\-blocking\-factor N
-use record size of Nx512 bytes (default N=20)
-.B \-B, \-\-read\-full\-records
-reblock as we read (for reading 4.2BSD pipes)
-.B \-\-backup[\=TYPE]
-back up files instead of overwriting (TYPE=numbered, existing, simple)
-.B \-C, \-\-directory DIR	
+Operation modifiers:
+.Bl -tag -width flag
+.It \-[0\-7][lmh]
+specify drive and density
+.It Fl ? , Fl \-help
+give this help list
+.It Fl a , Fl \-auto\-compress
+use archive suffix to determine the compression program
+.It Fl \-add\-file Ns \= Ns Ar FILE
+add given FILE to the archive (useful if its name starts with a dash)
+.It Fl \-anchored
+patterns match file name start
+.It Fl \-no\-anchored
+patterns match after any `/' (default for exclusion)
+.It Fl \-atime\-preserve
+preserve access times on dumped files, either by restoring the times
+.It Fl \-no\-auto\-compress
+do not use archive suffix to determine the compression program
+.It Fl b , Fl \-blocking\-factor Ar BLOCKS
+BLOCKS x 512 bytes per record
+.It Fl B , Fl \-read\-full\-records
+reblock as we read (for 4.2BSD pipes)
+.It Fl \-backup
+backup before removal, choose version CONTROL
+.It Fl C , Fl \-directory Ar DIR
 change to directory DIR
-.B \-\-checkpoint		
-print periodic checkpoints
-.B \-\-checkpoint\-action
-this action allows to specify an action to be executed upon hitting a
-checkpoint.  Recognized actions are: dot, echo (the default),
-echo\=string, ttyout\=string, exec\=cmdline, and sleep\=value.  Any number
-of `\-\-checkpoint\-action' options can be specified, the actions will be
-executed in order of their appearance in the command line.
-.B \-\-check\-device
-enables comparing device numbers.  This is the default.
-.B \-\-no\-check\-device
-disables comparing device numbers during preparatory stage of an 
-incremental dump.  
-This allows to avoid creating full dumps if the device numbers change 
-(e.g. when using an LVM snapshot)
-.B \-\-exclude=PATTERN
-exclude files matching PATTERN
-.B \-f, \-\-file [HOSTNAME:]F	
-use archive file or device F (otherwise value of TAPE environment variable; if unset, "\-", meaning stdin/stdout)
-.B \-F, \-\-info\-script F, \-\-new\-volume\-script F 
-run script at end of each tape (implies \-M)
-.B \-\-force\-local		
+.It Fl \-check\-device
+check device numbers when creating incremental archives (default)
+.It Fl \-no\-check\-device
+do not check device numbers when creating incremental archives
+.It Fl \-checkpoint
+display progress messages every NUMBERth record (default 10)
+.It Fl \-checkpoint\-action Ns \= Ns Ar ACTION
+execute ACTION on each checkpoint
+.It Fl \-delay\-directory\-restore
+delay setting modification times and permissions of extracted
+.It Fl \-no\-delay\-directory\-restore
+cancel the effect of --delay-directory-restore option
+.It Fl \-exclude Ns \= Ns Ar PATTERN
+exclude files, given as a PATTERN
+.It Fl \-exclude\-caches
+exclude contents of directories containing CACHEDIR.TAG, 
+.It Fl \-exclude\-caches\-all
+exclude directories containing CACHEDIR.TAG
+.It Fl \-exclude\-caches\-under
+exclude everything under directories containing CACHEDIR.TAG
+.It Fl \-exclude\-tag Ns \= Ns Ar FILE
+exclude contents of directories containing FILE, except
+.It Fl \-exclude\-tag\-all Ns \= Ns Ar FILE
+exclude directories containing FILE
+.It Fl \-exclude\-tag\-under Ns \= Ns Ar FILE
+exclude everything under directories containing FILE
+.It Fl \-exclude\-vcs
+exclude version control system directories
+.It Fl f , Fl \-file Ar ARCHIVE
+use archive file or device ARCHIVE
+.It Fl F , Fl \-info\-script , Fl \-new\-volume\-script Ar NAME
+run script at end of each tape (implies -M)
+.It Fl \-force\-local
 archive file is local even if it has a colon
-.B \-G, \-\-incremental	
-create/list/extract old GNU-format incremental backup
-.B \-g, \-\-listed\-incremental F 
-create/list/extract new GNU-format incremental backup
-.B \-\-group G
-set group to G while adding files
-.B \-h, \-\-dereference	
-don't dump symlinks; dump the files they point to
-.B \-\-hard\-dereference
-during archive creation, dereferences hard links and stores the files
-they refer to, instead of creating usual hard link members (type '1')
-.B \-\-help
-print help message
-.B \-i, \-\-ignore\-zeros	
-ignore blocks of zeros in archive (normally mean EOF)
-.B \-\-ignore\-case
-ignore case when excluding files
-.B \-\-ignore\-failed\-read	
-don't exit with non-zero status on unreadable files
-.B \-j, \-\-bzip2
-filter archive through bzip2, use to decompress .bz2 files.
-WARNING: some previous versions of tar used option \-I to 
-filter through bzip2.  When writing scripts, use \-\-bzip2 
-instead of \-j so that both older and newer tar versions
-will work.
-.B \-k, \-\-keep\-old\-files	
-keep existing files; don't overwrite them from archive
-.B \-K, \-\-starting\-file F	
-begin at file F in the archive
-.B \-\-lzma
-selects LZMA compression algorithm
-.B \-l, \-\-check\-links
+.It Fl g , Fl \-listed\-incremental Ar FILE
+handle new GNU-format incremental backup
+.It Fl G , Fl \-incremental
+handle old GNU-format incremental backup
+.It Fl \-group Ns \= Ns Ar NAME
+force NAME as group for added files
+.It Fl h , Fl \-dereference
+follow symlinks; archive and dump the files they point to
+.It Fl H , Fl \-format Ar FORMAT
+create archive of the given formatFORMAT is one of the following:
+.Bl -tag -width flag
+.It Fl \-format=gnu
+GNU tar 1.13.x format
+.It Fl \-format=oldgnu
+GNU format as per tar <= 1.12
+.It Fl \-format=pax
+POSIX 1003.1-2001 (pax) format
+.It Fl \-format=posix
+same as pax
+.It Fl \-format=ustar
+POSIX 1003.1-1988 (ustar) format
+.It Fl \-format=v7
+old V7 tar format
+.It Fl \-HANG
+hang for SECS seconds (default 3600)
+.It Fl \-hard\-dereference
+follow hard links; archive and dump the files they refer to
+.It Fl i , Fl \-ignore\-zeros
+ignore zeroed blocks in archive (means EOF)
+.It Fl I , Fl \-use\-compress\-program Ar PROG
+filter through PROG (must accept -d)
+.It Fl \-ignore\-case
+ignore case
+.It Fl \-no\-ignore\-case
+case sensitive matching (default)
+.It Fl \-ignore\-command\-error
+ignore exit codes of children
+.It Fl \-no\-ignore\-command\-error
+treat non-zero exit codes of children as error
+.It Fl \-ignore\-failed\-read
+do not exit with nonzero on unreadable files
+.It Fl \-index\-file Ns \= Ns Ar FILE
+send verbose output to FILE
+.It Fl j , Fl \-bzip2
+filter the archive through bzip2
+.It Fl J , Fl \-xz
+filter the archive through xz
+.It Fl k , Fl \-keep\-old\-files
+don't replace existing files when extracting
+.It Fl K , Fl \-starting\-file Ar MEMBER-NAME
+begin at member MEMBER-NAME in the archive
+.It Fl \-keep\-newer\-files
+don't replace existing files that are newer than their archive copies
+.It Fl l , Fl \-check\-links
 print a message if not all links are dumped
-.B \-L, \-\-tape\-length N	
-change tapes after writing N*1024 bytes
-.B \-m, \-\-touch
+.It Fl L , Fl \-tape\-length Ar NUMBER
+change tape after writing NUMBER x 1024 bytes
+.It Fl \-lzma
+filter the archive through lzma
+.It Fl \-lzop
+filter the archive through lzop
+.It Fl m , Fl \-touch
 don't extract file modified time
-.BI \-\-transform " expr"
-applies filename transformations.  
-The argument to this option can be a list of replace expressions, separated
-by semicolon (as in `sed').
-Filename transformations are applied to symbolic link targets during both
-creation and extraction.
-This option may be specified any number of
-times, the specified transofrmations will be applied in turn.
-.B \-M, \-\-multi\-volume	
+.It Fl M , Fl \-multi\-volume
 create/list/extract multi-volume archive
-.B \-\-mode M
-set permissions to M while adding files
-.B \-N, \-\-after\-date DATE, \-\-newer DATE
-only store files newer than DATE
-.B \-\-newer\-mtime DATE
-only store files whose contents have changed after DATE
-.B \-\-no\-anchored
-allow exclusion patterns to match any substring (the default)
-.B \-\-no\-ignore\-case
-match patterns case sensitively (the default)
-.B \-\-no\-recursion
-do not recurse into subdirectories
-.B \-o, \-\-no\-same\-owner
-extract files with owner set to current user (the default for non-root
-.B \-\-no\-same\-permissions
-apply umask to extracted files (the default for non-root users)
-.B \-\-no\-wildcards
-do not use wildcards when excluding files
-.B \-\-no\-wildcards\-match\-slash
-don't let wildcards match "/" when excluding files
-.B \-\-null
-for \-T, use "NUL" instead of newline as filename terminator
-.B \-\-numeric\-owner
+.It Fl \-mode Ns \= Ns Ar CHANGES
+force (symbolic) mode CHANGES for added files
+.It Fl \-mtime Ns \= Ns Ar DATE-OR-FILE
+set mtime for added files from DATE-OR-FILE
+.It Fl n , Fl \-seek
+archive is seekable
+.It Fl N , Fl \-newer , Fl \-after\-date Ar DATE-OR-FILE
+only store files newer than DATE-OR-FILE
+.It Fl \-newer\-mtime Ns \= Ns Ar DATE
+compare date and time when data changed only
+.It Fl \-null
+-T reads null-terminated names, disable -C
+.It Fl \-no\-null
+disable the effect of the previous --null option
+.It Fl \-numeric\-owner
 always use numbers for user/group names
-.B \-\-old\-archive, \-\-portability	
-write a V7 format archive, rather than ANSI format.  These options are
-deprecated, please use 
-.B \-\-format\=v7
-.B \-\-one\-file\-system	
-stay in local file system when creating an archive
-.B \-\-owner O
-set owner to O while adding files
-.B \-O, \-\-to\-stdout		
+.It Fl O , Fl \-to\-stdout
 extract files to standard output
-.B \-p, \-\-same\-permissions, \-\-preserve\-permissions 
-ignore umask when extracting files (the default for root)
-.B \-P, \-\-absolute\-names
+.It Fl \-occurrence
+process only the NUMBERth occurrence of each file in the archive;
+.It Fl \-old\-archive , Fl \-portability
+same as --format=v7
+.It Fl \-one\-file\-system
+stay in local file system when creating archive
+.It Fl \-overwrite
+overwrite existing files when extracting
+.It Fl \-overwrite\-dir
+overwrite metadata of existing directories when extracting (default)
+.It Fl \-no\-overwrite\-dir
+preserve metadata of existing directories
+.It Fl \-owner Ns \= Ns Ar NAME
+force NAME as owner for added files
+.It Fl p , Fl \-preserve\-permissions , Fl \-same\-permissions
+extract information about file permissions (default for superuser)
+.It Fl P , Fl \-absolute\-names
 don't strip leading `/'s from file names
-.B \-\-posix
-create POSIX compliant archive.  This option is deprecated,
-please use 
-.B \-\-format\=posix
-.B \-\-preserve		
-like \-p \-s
-.B \-R, \-\-block\-number	
+.It Fl \-pax\-option Ns \= Ns Ar keyword[[:]=value][,keyword[[:]=value]]...
+control pax keywords
+.It Fl \-posix
+same as --format=posix
+.It Fl \-preserve
+same as both -p and -s
+.It Fl \-quote\-chars Ns \= Ns Ar STRING
+additionally quote characters from STRING
+.It Fl \-no\-quote\-chars Ns \= Ns Ar STRING
+disable quoting for characters from STRING
+.It Fl \-quoting\-style Ns \= Ns Ar STYLE
+set name quoting style; see below for valid STYLE values
+.It Fl R , Fl \-block\-number
 show block number within archive with each message
-.B \-\-record\-size SIZE
-use SIZE bytes per record
-.B \-\-recursion
-recurse into directories (the default)
-.B \-\-recursive\-unlink
-remove existing directories before extracting directories of the same
-.B \-\-remove\-files		
+.It Fl \-record\-size Ns \= Ns Ar NUMBER
+NUMBER of bytes per record, multiple of 512
+.It Fl \-recursion
+recurse into directories (default)
+.It Fl \-no\-recursion
+avoid descending automatically in directories
+.It Fl \-recursive\-unlink
+empty hierarchies prior to extracting directory
+.It Fl \-remove\-files
 remove files after adding them to the archive
-.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.
-.B \-S, \-\-sparse		
+.It Fl \-restrict
+disable use of some potentially harmful options
+.It Fl \-rmt\-command Ns \= Ns Ar COMMAND
+use given rmt COMMAND instead of rmt
+.It Fl \-rsh\-command Ns \= Ns Ar COMMAND
+use remote COMMAND instead of rsh
+.It Fl s , Fl \-preserve\-order , Fl \-same\-order
+sort names to extract to match archive
+.It Fl S , Fl \-sparse
 handle sparse files efficiently
-.B \-s, \-\-same\-order, \-\-preserve\-order	
-list of names to extract is sorted to match archive
-.B \-\-same\-owner		
-extract files with owner as specified in archive (the default for
-.B \-\-show\-omitted\-dirs
-mention directories that are being skipped over
-.BI \-\-strip\-components " n"
-Strip the given number of leading directory components
-.B \-\-strip, \-\-strip\-components N
-Strips the first N components from archive members' pathnames when
-.B \-\-suffix SUFFIX
-append SUFFIX to make backup files (default ~)
-.B \-T, \-\-files\-from F	
-get names to extract or archive from file F
-.B \-\-totals
-display total bytes written after creating an archive
-.B \-U, \-\-unlink\-first
-unlink & recreate files instead of overwriting
-.B \-\-use\-compress\-program PROG
-filter the archive through PROG (which must accept \-d)
-.B \-v, \-\-verbose		
+.It Fl \-same\-owner
+try extracting files with the same ownership
+.It Fl \-no\-same\-owner
+extract files as yourself
+.It Fl \-no\-same\-permissions
+apply the user's umask when extracting permissions from the archive (default for ordinary users)
+.It Fl \-show\-defaults
+show tar defaults
+.It Fl \-show\-omitted\-dirs
+when listing or extracting, list each directory that does not match search criteria
+.It Fl \-show\-transformed\-names , Fl \-show\-stored\-names
+show file or archive names after transformation
+.It Fl \-sparse\-version Ns \= Ns Ar MAJOR[.MINOR]
+set version of the sparse format to use (implies --sparse)
+.It Fl \-strip\-components Ns \= Ns Ar NUMBER
+strip NUMBER leading components from file names on extraction
+.It Fl \-suffix Ns \= Ns Ar STRING
+backup before removal, override usual suffix ('~' unless overridden by environment variable SIMPLE_BACKUP_SUFFIX)
+.It Fl T , Fl \-files\-from Ar FILE
+get names to extract or create from FILE
+.It Fl \-to\-command Ns \= Ns Ar COMMAND
+pipe extracted files to another program
+.It Fl \-totals
+print total bytes after processing the archive; 
+.It Fl \-transform , Fl \-xform Ar EXPRESSION
+use sed replace EXPRESSION to transform file names
+.It Fl U , Fl \-unlink\-first
+remove each file prior to extracting over it
+.It Fl \-unquote
+unquote filenames read with -T (default)
+.It Fl \-no\-unquote
+do not unquote filenames read with -T
+.It Fl \-usage
+give a short usage message
+.It Fl \-utc
+print file modification dates in UTC
+.It Fl v , Fl \-verbose
 verbosely list files processed
-.B \-V, \-\-label NAME	
-create archive with volume name NAME
-.B \-\-version		
-print tar program version number
-.B \-\-volno\-file F
-keep track of current volume (of a multi-volume archive) in F
-.B \-w, \-\-interactive, \-\-confirmation	
+.It Fl V , Fl \-label Ar TEXT
+create archive with volume name TEXT; at list/extract time, use TEXT as a globbing pattern for volume name
+.It Fl \-version
+print program version
+.It Fl \-volno\-file Ns \= Ns Ar FILE
+use/update the volume number in FILE
+.It Fl w , Fl \-interactive , Fl \-confirmation
 ask for confirmation for every action
-.B \-W, \-\-verify		
+.It Fl W , Fl \-verify
 attempt to verify the archive after writing it
-.B \-\-wildcards
-use wildcards when excluding files (the default)
-.B \-\-wildcards\-match\-slash
-allow wildcards to match "/" (the default)
-.B \-X, \-\-exclude\-from=FILE	
-exclude files matching patterns listed in FILE
-.B \-Z, \-\-compress, \-\-uncompress      	
-filter the archive through compress
-.B \-z, \-\-gzip, \-\-gunzip, \-\-ungzip		
+.It Fl \-wildcards
+use wildcards (default for exclusion)
+.It Fl \-wildcards\-match\-slash
+wildcards match `/' (default for exclusion)
+.It Fl \-no\-wildcards\-match\-slash
+wildcards do not match `/'
+.It Fl \-no\-wildcards
+verbatim string matching
+.It Fl X , Fl \-exclude\-from Ar FILE
+exclude patterns listed in FILE
+.It Fl z , Fl \-gzip , Fl \-gunzip Fl \-ungzip
 filter the archive through gzip
-.B \-[0\-7][lmh]		
-specify drive and density
+.It Fl Z , Fl \-compress , Fl \-uncompress
+filter the archive through compress
 The behavior of tar is controlled by the following environment variables,
 among others:
-Device or file to use for the archive if \fB--file\fR is not specified.
-If this environment variable is unset, use stdin or stdout instead.
+.Bl -tag -width Ds
+Backup prefix to use when extracting, if
+.Fl \-suffix
+is not specified.
+The backup suffix defaults to `~' if neither is specified.
 Options to prepend to those specified on the command line, separated by
 whitespace.  Embedded backslashes may be used to escape whitespace or
 backslashes within an option.
-In addition, the value of the blocking factor is made available to info
-and checkpoint scripts via environment variable 
+.It Ev TAPE
+Device or file to use for the archive if 
+.Fl \-file
+is not specified.
+If this environment variable is unset, use stdin or stdout instead.
+Create archive.tar from files foo and bar.
+.Bd -literal -offset indent -compact
+tar \-cf archive.tar foo bar
+List all files in archive.tar verbosely.
+.Bd -literal -offset indent -compact
+tar \-tvf archive.tar
+Extract all files from archive.tar.
+.Bd -literal -offset indent -compact
+tar \-xf archive.tar
+.\" libarchive
+.Xr tar 5 ,
+.\" man-pages
+.Xr symlink 7 ,
+.Xr rmt 8
+.Nm tar
+command appeared in
+.At v7 .
 The GNU folks, in general, abhor man pages, and create info documents instead.
 Unfortunately, the info document describing tar is licensed under the GFDL with
-invariant cover texts, which violates the Debian Free Software Guidelines.  As
-a result, the info documentation for tar is not included in the Debian package.
-If you want to read the complete documentation for GNU tar, please refer to
-the online version at 
-.ce 1
-This man page was created for the Debian distribution.  It does not describe
-all of the functionality of tar, and it is often out of date.  Patches to 
-improve the coverage and/or accuracy of this man page are appreciated, and
-should be filed as wishlist severity bugs against the Debian tar package, 
-not submitted to the GNU tar maintainers.
+invariant cover texts, which makes it impossible to include any text
+from that document in this man page.
+Most of the text in this document was automatically extracted from the usage
+text in the source.
+It may not completely describe all features of the program.

More information about the arch-commits mailing list