| .TH TAR 1 "Mar 2010" "GNU" "tar" |
| .SH NAME |
| tar \- The GNU version of the tape archiver (tar) utility |
| .SH SYNOPSIS |
| .B tar |
| .I <operation> [options] |
| |
| .I Operations: |
| .nf |
| .B [-]A --catenate --concatenate |
| .B [-]c --create |
| .B [-]d --diff --compare |
| .B [-]r --append |
| .B [-]t --list |
| .B [-]u --update |
| .B [-]x --extract --get |
| .B --delete |
| .fi |
| |
| .I Common Options: |
| .nf |
| .BR -C ", " --directory " DIR" |
| .BR -f ", " --file " FILE" |
| .BR -j ", " --bzip2 |
| .BR -J ", " --xz |
| .BR -p ", " --preserve-permissions |
| .BR -v ", " --verbose |
| .BR -z ", " --gzip |
| .fi |
| |
| .I All Options: |
| .br |
| [ |
| .BR -a ", " --auto-compress |
| ] |
| [ |
| .BR --add-file " FILE" |
| ] |
| [ |
| .BR --anchored |
| ] |
| [ |
| .BR --atime-preserve |
| ] |
| [ |
| .BR -b ", " --blocking-factor " N" |
| ] |
| [ |
| .BR -B ", " --read-full-records |
| ] |
| [ |
| .BR --backup " BACKUP-TYPE" |
| ] |
| [ |
| .BR --block-compress |
| ] |
| [ |
| .BR -C ", " --directory " DIR" |
| ] |
| [ |
| .BR --checkpoint |
| ] |
| [ |
| .BR --delay-directory-restore |
| ] |
| [ |
| .BR --exclude " PATTERN" |
| ] |
| [ |
| .BR --exclude-caches |
| ] |
| [ |
| .BR --exclude-caches-all |
| ] |
| [ |
| .BR --exclude-caches-under |
| ] |
| [ |
| .BR --exclude-tag " FILE" |
| ] |
| [ |
| .BR --exclude-tag-all " FILE" |
| ] |
| [ |
| .BR --exclude-tag-under " FILE" |
| ] |
| [ |
| .BR -f ", " --file " [HOSTNAME:]FILE" |
| ] |
| [ |
| .BR -F ", " --info-script " FILE, " --new-volume-script " FILE" |
| ] |
| [ |
| .BR --force-local |
| ] |
| [ |
| .BR --format " FORMAT" |
| ] |
| [ |
| .BR -g ", " --listed-incremental " SNAPSHOT" |
| ] |
| [ |
| .BR -G ", " --incremental |
| ] |
| [ |
| .BR --group " GROUP" |
| ] |
| [ |
| .BR -h ", " --dereference |
| ] |
| [ |
| .BR --help |
| ] |
| [ |
| .BR -i ", " --ignore-zeros |
| ] |
| [ |
| .BR -I ", " --use-compress-program " PROG" |
| ] |
| [ |
| .BR --ignore-case |
| ] |
| [ |
| .BR --ignore-command-error |
| ] |
| [ |
| .BR --ignore-failed-read |
| ] |
| [ |
| .BR --index-file " FILE" |
| ] |
| [ |
| .BR -j ", " --bzip2 |
| ] |
| [ |
| .BR -J ", " --xz |
| ] |
| [ |
| .BR -k ", " --keep-old-files |
| ] |
| [ |
| .BR -K ", " --starting-file " FILE" |
| ] |
| [ |
| .BR --keep-newer-files |
| ] |
| [ |
| .BR -l ", " --check-links |
| ] |
| [ |
| .BR -L ", " --tape-length " N" |
| ] |
| [ |
| .BR --lzip |
| ] |
| [ |
| .BR --lzma |
| ] |
| [ |
| .BR --lzop |
| ] |
| [ |
| .BR -m ", " --touch ", " --modification-time |
| ] |
| [ |
| .BR -M ", " --multi-volume |
| ] |
| [ |
| .BR --mode " PERMISSIONS" |
| ] |
| [ |
| .BR --mtime " DATE" |
| ] |
| [ |
| .BR -N ", " --after-date " DATE, " --newer " DATE" |
| ] |
| [ |
| .BR --newer-mtime " DATE" |
| ] |
| [ |
| .BR --no-anchored |
| ] |
| [ |
| .BR --no-auto-compress |
| ] |
| [ |
| .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 |
| ] |
| [ |
| .BR --no-wildcards-match-slash |
| ] |
| [ |
| .BR --null |
| ] |
| [ |
| .BR --numeric-owner |
| ] |
| [ |
| .BR -o ", " --old-archive ", " --portability ", " --no-same-owner |
| ] |
| [ |
| .BR -O ", " --to-stdout |
| ] |
| [ |
| .BR --occurrence " NUM" |
| ] |
| [ |
| .BR --one-file-system |
| ] |
| [ |
| .BR --overwrite |
| ] |
| [ |
| .BR --overwrite-dir |
| ] |
| [ |
| .BR --owner " USER" |
| ] |
| [ |
| .BR -p ", " --same-permissions ", " --preserve-permissions |
| ] |
| [ |
| .BR -P ", " --absolute-names |
| ] |
| [ |
| .BR --pax-option " KEYWORD-LIST" |
| ] |
| [ |
| .BR --posix |
| ] |
| [ |
| .BR --preserve |
| ] |
| [ |
| .BR --quote-chars " STRING" |
| ] |
| [ |
| .BR --quote-style " STYLE" |
| ] |
| [ |
| .BR -R ", " --block-number |
| ] |
| [ |
| .BR --record-size " SIZE" |
| ] |
| [ |
| .BR --recursion |
| ] |
| [ |
| .BR --recursive-unlink |
| ] |
| [ |
| .BR --remove-files |
| ] |
| [ |
| .BR --restrict |
| ] |
| [ |
| .BR --rmt-command " CMD" |
| ] |
| [ |
| .BR --rsh-command " CMD" |
| ] |
| [ |
| .BR -s ", " --same-order ", " --preserve-order |
| ] |
| [ |
| .BR -S ", " --sparse |
| ] |
| [ |
| .BR --same-owner |
| ] |
| [ |
| .BR --show-defaults |
| ] |
| [ |
| .BR --show-omitted-dirs |
| ] |
| [ |
| .BR --show-transformed-names ", " --show-stored-names |
| ] |
| [ |
| .BR --strip-components " NUMBER" |
| ] |
| [ |
| .BR --suffix " SUFFIX" |
| ] |
| [ |
| .BR -T ", " --files-from " FILE" |
| ] |
| [ |
| .BR --test-label |
| ] |
| [ |
| .BR --to-command " COMMAND" |
| ] |
| [ |
| .BR --transform " EXPRESSION" |
| ] |
| [ |
| .BR --totals |
| ] |
| [ |
| .BR -U ", " --unlink-first |
| ] |
| [ |
| .BR --unquote |
| ] |
| [ |
| .BR --utc |
| ] |
| [ |
| .BR -v ", " --verbose |
| ] |
| [ |
| .BR -V ", " --label " NAME" |
| ] |
| [ |
| .BR --version |
| ] |
| [ |
| .BR --volno-file " FILE" |
| ] |
| [ |
| .BR -w ", " --interactive ", " --confirmation |
| ] |
| [ |
| .BR -W ", " --verify |
| ] |
| [ |
| .BR --wildcards |
| ] |
| [ |
| .BR --wildcards-match-slash |
| ] |
| [ |
| .BR -X ", " --exclude-from " FILE" |
| ] |
| [ |
| .BR -z ", " --gzip ", " --gunzip ", " --ungzip |
| ] |
| [ |
| .BR -Z ", " --compress ", " --uncompress |
| ] |
| [ |
| .BR -[0-7][lmh] |
| ] |
| .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 |
| 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 -xvf foo.tar |
| verbosely extract foo.tar |
| .TP |
| .B tar -xzf foo.tar.gz |
| extract gzipped foo.tar.gz |
| .TP |
| .B tar -cjf foo.tar.bz2 bar/ |
| create bzipped tar archive of the directory bar 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.gz blah.txt |
| extract the file blah.txt from foo.tar.gz |
| .P |
| Note: When working with archives, specifying the compression option is often |
| times unnecessary as \fBtar\fR will automatically detect the compression type |
| based on the suffix of the archive. |
| .SH "FUNCTION LETTERS" |
| .TP |
| .B One of the following options must be used: |
| .TP |
| .BR -A ", " --catenate ", " --concatenate |
| append tar files to an archive |
| .TP |
| .BR -c ", " --create |
| create a new archive |
| .TP |
| .BR -d ", " --diff ", " --compare |
| find differences between archive and file system |
| .TP |
| .BR -r ", " --append |
| append files to the end of an archive |
| .TP |
| .BR -t ", " --list |
| list the contents of an archive |
| .TP |
| .BR -u ", " --update |
| only append files that are newer than the existing in archive |
| .TP |
| .BR -x ", " --extract ", " --get |
| extract files from an archive |
| .TP |
| .BR --delete |
| 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:]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 |
| .TP |
| .BR -J ", " --xz |
| filter archive through xz; use to decompress .xz files |
| .TP |
| .BR -p ", " --preserve-permissions |
| extract all protection information |
| .TP |
| .BR -v ", " --verbose |
| verbosely list files processed |
| .TP |
| .BR -z ", " --gzip ", " --ungzip |
| filter the archive through gzip |
| .SH "ALL OPTIONS" |
| .TP |
| .BR -a ", " --auto-compress |
| use archive suffix to determine the compression program |
| .TP |
| .BR --add-file " FILE" |
| add specified FILE to the archive (useful if FILE starts with a dash) |
| .TP |
| .BR --anchored |
| patterns will match the start of file names |
| .TP |
| .BR --atime-preserve |
| don't change access times of files that are archived |
| .TP |
| .BR -b ", " --blocking-factor " N" |
| block size of Nx512 bytes (default N=20) |
| .TP |
| .BR -B ", " --read-full-blocks |
| reblock as we read (for reading 4.2BSD pipes) |
| .TP |
| .BR --backup " BACKUP-TYPE" |
| backup files instead of deleting them using BACKUP-TYPE simple or |
| numbered |
| .TP |
| .BR --block-compress |
| block the output of compression program for tapes |
| .TP |
| .BR -C ", " --directory " DIR" |
| change to directory DIR |
| .TP |
| .BR --checkpoint |
| print directory names while reading the archive |
| .TP |
| .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 "-", 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 its name contains a colon |
| .TP |
| .BR --format " FORMAT" |
| selects the format of the created archive |
| .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 |
| .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 archive symlinks; archive the files they point to |
| .TP |
| .BR --help |
| like this manpage, but not as cool |
| .TP |
| .BR -i ", " --ignore-zeros |
| ignore blocks of zeros in archive (normally mean EOF) |
| .TP |
| .BR -I ", " --use-compress-program " PROG" |
| access the archive through PROG (which is generally a compression program; |
| it must accept the \fI-d\fR option) |
| .TP |
| .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 |
| .BR --index-file " FILE" |
| send verbose output to FILE instead of stdout |
| .TP |
| .BR -j ", " --bzip2 |
| filter archive through bzip2, use to decompress .bz2 files |
| .TP |
| .BR -J ", " --xz |
| filter archive through xz; use to decompress .xz files |
| .TP |
| .BR -k ", " --keep-old-files |
| keep existing files; don't overwrite them from archive |
| .TP |
| .BR -K ", " --starting-file " FILE" |
| 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 ", " --check-links |
| warn if number of hard links to the file on the filesystem mismatchs |
| the number of links recorded in the archive |
| .TP |
| .BR -L ", " --tape-length " N" |
| change tapes after writing N*1024 bytes |
| .TP |
| .BR -m ", " --touch ", " --modification-time |
| don't extract file modified time |
| .TP |
| .BR -M ", " --multi-volume |
| create/list/extract multi-volume archive |
| .TP |
| .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 |
| .TP |
| .BR --newer-mtime " DATE" |
| like \fI--newer\fR, but only store files that were modified since DATE |
| .TP |
| .BR --no-anchored |
| match any subsequenceof the name's components with \fI--exclude\fR |
| .TP |
| .BR --no-auto-compress |
| do not use archive suffix to determine the compression program |
| .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 |
| .BR --no-wildcards-match-slash |
| wildcards do not match slashes (/) with \fI--exclude\fR |
| .TP |
| .BR --null |
| \fI--files-from\fR reads null-terminated names, disable \fI--directory\fR |
| .TP |
| .BR --numeric-owner |
| always use numbers for user/group names |
| .TP |
| .BR -o ", " --old-archive ", " --portability |
| like \fI--format=v7\fR; \fI-o\fR exhibits this behavior when creating an |
| archive (deprecated behavior) |
| .TP |
| .BR -o ", " --no-same-owner |
| do not attempt to restore ownership when extracting; \fI-o\fR exhibits |
| this behavior when extracting an archive |
| .TP |
| .BR -O ", " --to-stdout |
| extract files to standard output |
| .TP |
| .BR --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 |
| .BR --one-file-system |
| stay in local file system when creating an archive |
| .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 |
| .BR --overwrite-dir |
| overwrite directory metadata when extracting |
| .TP |
| .BR --owner " 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 ", " --preserve-permissions ", " --same-permissions |
| extract all protection information |
| .TP |
| .BR -P ", " --absolute-names |
| don't strip leading `/'s from file names |
| .TP |
| .BR --pax-option " KEYWORD-LIST" |
| used only with POSIX.1-2001 archives to modify the way \fBtar\fR handles |
| extended header keywords |
| .TP |
| .BR --posix |
| like \fI--format=posix\fR |
| .TP |
| .BR --preserve |
| 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 |
| .TP |
| .BR --record-size " SIZE" |
| use SIZE bytes per record when accessing archives |
| .TP |
| .BR --recursion |
| recurse into directories |
| .TP |
| .BR --recursive-unlink |
| remove existing directories before extracting directories of the same name |
| .TP |
| .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 |
| .BR --rsh-command " CMD" |
| use remote CMD instead of \fBrsh\fR(1) |
| .TP |
| .BR -s ", " --same-order ", " --preserve-order |
| list of names to extract is sorted to match archive |
| .TP |
| .BR -S ", " --sparse |
| handle sparse files efficiently |
| .TP |
| .BR --same-owner |
| create extracted files with the same ownership |
| .TP |
| .BR --show-defaults |
| display the default options used by \fBtar\fR |
| .TP |
| .BR --show-omitted-dirs |
| print directories \fBtar\fR skips while operating on an archive |
| .TP |
| .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 |
| .TP |
| .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 --utc |
| display file modification dates in UTC |
| .TP |
| .BR -v ", " --verbose |
| verbosely list files processed |
| .TP |
| .BR -V ", " --label " NAME" |
| create archive with volume name NAME |
| .TP |
| .BR --version |
| print \fBtar\fR program version number |
| .TP |
| .BR --volno-file " FILE" |
| keep track of which volume of a multi-volume archive its working in |
| FILE; used with \fI--multi-volume\fR |
| .TP |
| .BR -w ", " --interactive ", " --confirmation |
| ask for confirmation for every action |
| .TP |
| .BR -W ", " --verify |
| attempt to verify the archive after writing it |
| .TP |
| .BR --wildcards |
| use wildcards with \fI--exclude\fR |
| .TP |
| .BR --wildcards-match-slash |
| wildcards match slashes (/) with \fI--exclude\fR |
| .TP |
| .BR -X ", " --exclude-from " FILE" |
| exclude files listed in FILE |
| .TP |
| .BR -z ", " --gzip ", " --gunzip ", " --ungzip |
| filter the archive through gzip |
| .TP |
| .BR -Z ", " --compress ", " --uncompress |
| filter the archive through compress |
| .TP |
| .BR -[0-7][lmh] |
| specify drive and density |
| .SH BUGS |
| The GNU folks, in general, abhor man pages and create info documents instead. |
| The maintainer of \fBtar\fR falls into this category. Thus, this man page may |
| not be complete nor current, and it is 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 lovingly 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 |