1 .\" This file is part of GNU tar. -*- nroff -*-
2 .\" Copyright 2013-2014 Free Software Foundation, Inc.
4 .\" GNU tar is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 3 of the License, or
7 .\" (at your option) any later version.
9 .\" GNU tar is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 .\" GNU General Public License for more details.
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with this program. If not, see <http://www.gnu.org/licenses/>.
16 .TH TAR 1 "February 22, 2014" "TAR" "GNU TAR Manual"
18 tar \- an archiving utility
21 \fBtar\fR {\fBA\fR|\fBc\fR|\fBd\fR|\fBr\fR|\fBt\fR|\fBu\fR|\fBx\fR}\
22 [\fBGnSkUWOmpsMBiajJzZhPlRvwo\fR] [\fIARG\fR...]
25 \fBtar\fR \fB\-A\fR [\fIOPTIONS\fR] \fIARCHIVE\fR \fIARCHIVE\fR
27 \fBtar\fR \fB\-c\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
29 \fBtar\fR \fB\-d\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
31 \fBtar\fR \fB\-t\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
33 \fBtar\fR \fB\-r\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
35 \fBtar\fR \fB\-u\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
37 \fBtar\fR \fB\-x\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
40 \fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate} [\fIOPTIONS\fR] \fIARCHIVE\fR \fIARCHIVE\fR
42 \fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
44 \fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
46 \fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
48 \fBtar\fR \fB\-\-append\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
50 \fBtar\fR \fB\-\-list\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
52 \fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fILABEL\fR...]
54 \fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
56 \fBtar\fR \fB\-\-update\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
58 \fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
60 This manpage is a short description of GNU \fBtar\fR. For a detailed
61 discussion, including examples and usage recommendations, refer to the
62 \fBGNU Tar Manual\fR available in texinfo format. If the \fBinfo\fR
63 reader and the tar documentation are properly installed on your
70 should give you access to the complete manual.
72 You can also view the manual using the info mode in
74 or find it in various formats online at
77 .B http://www.gnu.org/software/tar/manual
80 If any discrepancies occur between this manpage and the
81 \fBGNU Tar Manual\fR, the later shall be considered the authoritative
86 is an archiving program designed to store multiple files in a single
87 file (an \fBarchive\fR), and to manipulate such archives. The archive
88 can be either a regular file or a device (e.g. a tape drive, hence the name
89 of the program, which stands for \fBt\fRape \fBar\fRchiver), which can
90 be located either on the local or on a remote machine.
94 Options to GNU \fBtar\fR can be given in three different styles.
96 .BR "traditional style" ,
97 the first argument is a cluster of option letters and all subsequent
98 arguments supply arguments to those options that require them. The
99 arguments are read in the same order as the option letters. Any
100 command line words that remain after all options has been processed
101 are treated as non-optional arguments: file or archive member names.
103 For example, the \fBc\fR option requires creating the archive, the
104 \fBv\fR option requests the verbose operation, and the \fBf\fR option
105 takes an argument that sets the name of the archive to operate upon.
106 The following command, written in the traditional style, instructs tar
107 to store all files from the directory
109 into the archive file
111 verbosely listing the files being archived:
114 .B tar cfv a.tar /etc
118 .BR "UNIX " or " short-option style" ,
119 each option letter is prefixed with a single dash, as in other command
120 line utilities. If an option takes argument, the argument follows it,
121 either as a separate command line word, or immediately following the
122 option. However, if the option takes an \fBoptional\fR argument, the
123 argument must follow the option letter without any intervening
124 whitespace, as in \fB\-g/tmp/snar.db\fR.
126 Any number of options not taking arguments can be
127 clustered together after a single dash, e.g. \fB\-vkp\fR. Options
128 that take arguments (whether mandatory or optional), can appear at
129 the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
131 The example command above written in the
132 .B short-option style
136 .B tar -cvf a.tar /etc
138 .B tar -c -v -f a.tar /etc
142 .BR "GNU " or " long-option style" ,
143 each option begins with two dashes and has a meaningful name,
144 consisting of lower-case letters and dashes. When used, the long
145 option can be abbreviated to its initial letters, provided that
146 this does not create ambiguity. Arguments to long options are
147 supplied either as a separate command line word, immediately following
148 the option, or separated from the option by an equals sign with no
149 intervening whitespace. Optional arguments must always use the latter
152 Here are several ways of writing the example command in this style:
155 .B tar --create --file a.tar --verbose /etc
157 or (abbreviating some options):
159 .B tar --cre --file=a.tar --verb /etc
162 The options in all three styles can be intermixed, although doing so
163 with old options is not encouraged.
165 The options listed in the table below tell GNU \fBtar\fR what
166 operation it is to perform. Exactly one of them must be given.
167 Meaning of non-optional arguments depends on the operation mode
170 \fB\-A\fR, \fB\-\-catenate\fR, \fB\-\-concatenate\fR
171 Append archive to the end of another archive. The arguments are
172 treated as the names of archives to append. All archives must be of
173 the same format as the archive they are appended to, otherwise the
174 resulting archive might be unusable with non-GNU implementations of
175 \fBtar\fR. Notice also that when more than one archive is given, the
176 members from archives other than the first one will be accessible in
177 the resulting archive only if using the \fB\-i\fR
178 (\fB\-\-ignore\-zeros) option.
180 Compressed archives cannot be concatenated.
182 \fB\-c\fR, \fB\-\-create\fR
183 Create a new archive. Arguments supply the names of the files to be
184 archived. Directories are archived recursively, unless the
185 \fB\-\-no\-recursion\fR option is given.
187 \fB\-d\fR, \fB\-\-diff\fR, \fB\-\-compare\fR
188 Find differences between archive and file system. The arguments are
189 optional and specify archive members to compare. If not given, the
190 current working directory is assumed.
193 Delete from the archive. The arguments supply names of the archive
194 members to be removed. At least one argument must be given.
196 This option does not operate on compressed archives. There is no
197 short option equivalent.
199 \fB\-r\fR, \fB\-\-append\fR
200 Append files to the end of an archive. Arguments have the same
201 meaning as for \fB\-c\fR (\fB\-\-create).
203 \fB\-t\fR, \fB\-\-list\fR
204 List the contents of an archive. Arguments are optional. When given,
205 they specify the names of the members to list.
208 Test the archive volume label and exit. When used without arguments,
209 it prints the volume label (if any) and exits with status \fB0\fR.
210 When one or more command line arguments are given.
212 compares the volume label with each argument. It exits with code
213 \fB0\fR if a match is found, and with code \fB1\fR otherwise. No
214 output is displayed, unless used together with the \fB\-v\fR
215 (\fB\-\-verbose\fR) option.
217 There is no short option equivalent for this option.
219 \fB\-u\fR, \fB\-\-update\fR
220 Append files which are newer than the corresponding copy in the
221 archive. Arguments have the same meaning as with \fB\-c\fR and
224 \fB\-x\fR, \fB\-\-extract\fR, \fB\-\-get\fR
225 Extract files from an archive. Arguments are optional. When given,
226 they specify names of the archive members to be extracted.
229 \fB\-\-show\-defaults\fR
230 Show built-in defaults for various \fBtar\fR options and exit. No
231 arguments are allowed.
233 \fB\-?\fR, \fB\-\-help
234 Display a short option summary and exit. No arguments allowed.
237 Display a list of available options and exit. No arguments allowed.
240 Print program version and copyright information and exit.
242 .SS Operation modifiers
244 \fB\-\-check\-device\fR
245 Check device numbers when creating incremental archives (default).
247 \fB\-g\fR, \fB\-\-listed\-incremental\fR=\fIFILE\fR
248 Handle new GNU-format incremental backups. \fIFILE\fR is the name of
249 a \fBsnapshot file\fR, where tar stores additional information which
250 is used to decide which files changed since the previous incremental
251 dump and, consequently, must be dumped again. If \fIFILE\fR does not
252 exist when creating an archive, it will be created and all files will
253 be added to the resulting archive (the \fBlevel 0\fR dump). To create
254 incremental archives of non-zero level \fBN\fR, create a copy of the
255 snapshot file created during the level \fBN-1\fR, and use it as
258 When listing or extracting, the actual contents of \fIFILE\fR is not
259 inspected, it is needed only due to syntactical requirements. It is
260 therefore common practice to use \fB/dev/null\fR in its place.
262 \fB\-G\fR, \fB\-\-incremental\fR
263 Handle old GNU-format incremental backups.
265 \fB\-\-ignore\-failed\-read\fR
266 Do not exit with nonzero on unreadable files.
268 \fB\-\-level\fR=\fINUMBER\fR
269 Set dump level for created listed-incremental archive. Currently only
270 \fB\-\-level=0\fR is meaningful: it instructs \fBtar\fR to truncate
271 the snapshot file before dumping, thereby forcing a level 0 dump.
273 \fB\-n\fR, \fB\-\-seek\fR
274 Assume the archive is seekable. Normally \fBtar\fR determines
275 automatically whether the archive can be seeked or not. This option
276 is intended for use in cases when such recognition fails. It takes
277 effect only if the archive is open for reading (e.g. with
283 \fB\-\-no\-check\-device\fR
284 Do not check device numbers when creating incremental archives.
287 Assume the archive is not seekable.
289 \fB\-\-occurrence\fR[=\fIN\fR]
290 Process only the \fIN\fRth occurrence of each file in the
291 archive. This option is valid only when used with one of the
292 following subcommands: \fB\-\-delete\fR, \fB\-\-diff\fR,
293 \fB\-\-extract\fR or \fB\-\-list\fR and when a list of files is given
294 either on the command line or via the \fB\-\fRT option. The default
298 Disable the use of some potentially harmful options.
300 \fB\-\-sparse\-version\fR=\fIMAJOR\fR[.\fIMINOR\fR]
301 Set version of the sparse format to use (implies \fB\-\-sparse\fR).
304 Valid argument values are
308 For a detailed discussion of sparse formats, refer to the \fBGNU Tar
309 Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR". Using \fBinfo\fR
310 reader, it can be accessed running the following command:
311 .BR "info tar 'Sparse Formats'" .
313 \fB\-S\fR, \fB\-\-sparse\fR
314 Handle sparse files efficiently. Some files in the file system may
315 have segments which were actually never written (quite often these are
316 database files created by such systems as \fBDBM\fR). When given this
317 option, \fBtar\fR attempts to determine if the file is sparse prior to
318 archiving it, and if so, to reduce the resulting archive size by not
319 dumping empty parts of the file.
320 .SS Overwrite control
321 These options control \fBtar\fR actions when extracting a file over
322 an existing copy on disk.
324 \fB\-k\fR, \fB\-\-keep\-old\-files\fR
325 Don't replace existing files when extracting.
327 \fB\-\-keep\-newer\-files\fR
328 Don't replace existing files that are newer than their archive copies.
330 \fB\-\-no\-overwrite\-dir\fR
331 Preserve metadata of existing directories.
333 \fB\-\-one\-top\-level\fR[\fB=\fIDIR\fR]
334 Extract all files into \fIDIR\fR, or, if used without argument, into a
335 subdirectory named by the base name of the archive (minus standard
336 compression suffixes recognizable by \fB\-\-auto\-compress).
339 Overwrite existing files when extracting.
341 \fB\-\-overwrite\-dir\fR
342 Overwrite metadata of existing directories when extracting (default).
344 \fB\-\-recursive\-unlink\fR
345 Recursively remove all files in the directory prior to extracting it.
347 \fB\-\-remove\-files\fR
348 Remove files from disk after adding them to the archive.
350 \fB\-U\fR, \fB\-\-unlink\-first\fR
351 Remove each file prior to extracting over it.
353 \fB\-W\fR, \fB\-\-verify\fR
354 Verify the archive after writing it.
355 .SS Output stream selection
357 \fB\-\-ignore\-command\-error\fR
359 Ignore subprocess exit codes.
361 \fB\-\-no\-ignore\-command\-error\fR
362 Treat non-zero exit codes of children as error (default).
364 \fB\-O\fR, \fB\-\-to\-stdout\fR
365 Extract files to standard output.
367 \fB\-\-to\-command\fR=\fICOMMAND\fR
368 Pipe extracted files to \fICOMMAND\fR. The argument is the pathname
369 of an external program, optionally with command line arguments. The
370 program will be invoked and the contents of the file being extracted
371 supplied to it on its standard output. Additional data will be
372 supplied via the following environment variables:
376 Type of the file. It is a single letter with the following meaning:
388 Currently only regular files are supported.
391 File mode, an octal number.
394 The name of the file.
397 Name of the file as stored in the archive.
400 Name of the file owner.
403 Name of the file owner group.
406 Time of last access. It is a decimal number, representing seconds
407 since the Epoch. If the archive provides times with nanosecond
408 precision, the nanoseconds are appended to the timestamp after a
412 Time of last modification.
415 Time of last status change.
421 UID of the file owner.
424 GID of the file owner.
428 Additionally, the following variables contain information about
429 \fBtar\fR operation mode and the archive being processed:
432 GNU \fBtar\fR version number.
435 The name of the archive \fBtar\fR is processing.
437 .B TAR_BLOCKING_FACTOR
438 Current blocking factor, i.e. number of 512-byte blocks in a record.
441 Ordinal number of the volume \fBtar\fR is processing (set if
442 reading a multi-volume archive).
445 Format of the archive being processed. One of:
452 A short option (with a leading dash) describing the operation \fBtar\fR is
455 .SS Handling of file attributes
457 \fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
458 Preserve access times on dumped files, either by restoring the times
459 after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
460 not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
462 \fB\-\-delay\-directory\-restore\fR
463 Delay setting modification times and permissions of extracted
464 directories until the end of extraction. Use this option when
465 extracting from an archive which has unusual member ordering.
467 \fB\-\-group\fR=\fINAME\fR
468 Force \fINAME\fR as group for added files.
470 \fB\-\-mode\fR=\fICHANGES\fR
471 Force symbolic mode \fICHANGES\fR for added files.
473 \fB\-\-mtime\fR=\fIDATE-OR-FILE\fR
474 Set mtime for added files. \fIDATE-OR-FILE\fR is either a date/time
475 in almost arbitrary formate, or the name of an existing file. In the
476 latter case the mtime of that file will be used.
478 \fB\-m\fR, \fB\-\-touch\fR
479 Don't extract file modified time.
481 \fB\-\-no\-delay\-directory\-restore\fR
482 Cancel the effect of the prior \fB\-\-delay\-directory\-restore\fR option.
484 \fB\-\-no\-same\-owner\fR
485 Extract files as yourself (default for ordinary users).
487 \fB\-\-no\-same\-permissions\fR
488 Apply the user's umask when extracting permissions from the archive
489 (default for ordinary users).
491 \fB\-\-numeric\-owner\fR
492 Always use numbers for user/group names.
494 \fB\-\-owner\fR=\fINAME\fR
495 Force \fINAME\fR as owner for added files.
497 \fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
498 extract information about file permissions (default for superuser)
501 Same as both \fB\-p\fR and \fB\-s\fR.
503 \fB\-\-same\-owner\fR
504 Try extracting files with the same ownership as exists in the archive
505 (default for superuser).
507 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
508 Sort names to extract to match archive
510 \fB\-\-sort=\fIORDER\fR
511 When creating an archive, sort directory entries according to
512 \fIORDER\fR, which is one of
517 The default is \fB\-\-sort=none\fR, which stores archive members in
518 the same order as returned by the operating system.
520 Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
521 is uniform and reproducible.
523 Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
524 creating the archive and thus can considerably speed up archivation.
525 This sorting order is supported only if the underlying system provides
526 the necessary information.
527 .SS Device selection and switching
529 \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
530 Use archive file or device \fIARCHIVE\fR. If this option is not
531 given, \fBtar\fR will first examine the environment variable `TAPE'.
532 If it is set, its value will be used as the archive name. Otherwise,
533 \fBtar\fR will assume the compiled-in default. The default
534 value can be inspected either using the
535 .B \-\-show\-defaults
536 option, or at the end of the \fBtar \-\-help\fR output.
538 An archive name that has a colon in it specifies a file or device on a
539 remote machine. The part before the colon is taken as the machine
540 name or IP address, and the part after it as the file or device
544 --file=remotehost:/dev/sr0
547 An optional username can be prefixed to the hostname, placing a \fB@\fR
550 By default, the remote host is accessed via the
552 command. Nowadays it is common to use
554 instead. You can do so by giving the following command line option:
557 --rsh-command=/usr/bin/ssh
560 The remote mashine should have the
562 command installed. If its pathname does not match \fBtar\fR's
563 default, you can inform \fBtar\fR about the correct pathname using the
567 \fB\-\-force\-local\fR
568 Archive file is local even if it has a colon.
570 \fB\-\fRF, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
571 Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The
572 command can include arguments. When started, it will inherit \fBtar\fR's
573 environment plus the following variables:
577 GNU \fBtar\fR version number.
580 The name of the archive \fBtar\fR is processing.
582 .B TAR_BLOCKING_FACTOR
583 Current blocking factor, i.e. number of 512-byte blocks in a record.
586 Ordinal number of the volume \fBtar\fR is processing (set if
587 reading a multi-volume archive).
590 Format of the archive being processed. One of:
598 A short option (with a leading dash) describing the operation \fBtar\fR is
602 File descriptor which can be used to communicate the new volume name
608 If the info script fails, \fBtar\fR exits; otherwise, it begins writing
612 \fB\-L\fR, \fB\-\-tape\-length\fR=\fN\fR
613 Change tape after writing \fIN\fRx1024 bytes. If \fIN\fR is followed
614 by a size suffix (see the subsection
616 below), the suffix specifies the multiplicative factor to be used
622 \fB\-M\fR, \fB\-\-multi\-volume\fR
623 Create/list/extract multi-volume archive.
625 \fB\-\-rmt\-command\fR=\fICOMMAND\fR
626 Use \fICOMMAND\fR instead of \fBrmt\fR when accessing remote
627 archives. See the description of the
631 \fB\-\-rsh\-command\fR=\fICOMMAND\fR
632 Use \fICOMMAND\fR instead of \fBrsh\fR when accessing remote
633 archives. See the description of the
637 \fB\-\-volno\-file\fR=\fIFILE\fR
638 When this option is used in conjunction with
639 .BR \-\-multi\-volume ,
641 will keep track of which volume of a multi-volume archive it is
642 working in \fIFILE\fR.
645 \fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
646 Set record size to \fIBLOCKS\fRx\fB512\fR bytes.
648 \fB\-B\fR, \fB\-\-read\-full\-records\fR
649 When listing or extracting, accept incomplete input records after
652 \fB\-i\fR, \fB\-\-ignore\-zeros\fR
653 Ignore zeroed blocks in archive. Normally two consecutive 512-blocks
654 filled with zeroes mean EOF and tar stops reading after encountering
655 them. This option instructs it to read further and is useful when
656 reading archives created with the \fB\-A\fR option.
658 \fB\-\-record\-size\fR=\fINUMBER\fR
659 Set record size. \fINUMBER\fR is the number of bytes per record. It
660 must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
661 suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
663 .BR "Size suffixes" ,
664 for a list of valid suffixes.
665 .SS Archive format selection
667 \fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
668 Create archive of the given format. Valid formats are:
672 GNU tar 1.13.x format
675 GNU format as per tar <= 1.12.
677 \fBpax\fR, \fBposix\fR
678 POSIX 1003.1-2001 (pax) format.
681 POSIX 1003.1-1988 (ustar) format.
687 \fB\-\-old\-archive\fR, \fB\-\-portability\fR
688 Same as \fB\-\-format=v7\fR.
690 \fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
691 Control pax keywords when creating \fBPAX\fR archives (\fB\-H
692 pax\fR). This option is equivalent to the \fB\-o\fR option of the
696 Same as \fB\-\-format=posix\fR.
698 \fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
699 Create archive with volume name \fITEXT\fR. If listing or extracting,
700 use \fITEXT\fR as a globbing pattern for volume name.
701 .SS Compression options
703 \fB\-a\fR, \fB\-\-auto\-compress\fR
704 Use archive suffix to determine the compression program.
706 \fB\-\fRI, \fB\-\-use\-compress\-program\fI=\fICOMMAND\fR
707 Filter data through \fICOMMAND\fR. It must accept the \fB\-d\fR
708 option, for decompression. The argument can contain command line
711 \fB\-j\fR, \fB\-\-bzip2\fR
712 Filter the archive through
715 \fB\-J\fR, \fB\-\-xz\fR
716 Filter the archive through
720 Filter the archive through
724 Filter the archive through
728 Filter the archive through
731 \fB\-\-no\-auto\-compress\fR
732 Do not use archive suffix to determine the compression program.
734 \fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
735 Filter the archive through
738 \fB\-\fRZ, \fB\-\-compress\fR, \fB\-\-uncompress\fR
739 Filter the archive through
741 .SS Local file selection
743 \fB\-\-add\-file\fR=\fIFILE\fR
744 Add \fIFILE\fR to the archive (useful if its name starts with a dash).
746 \fB\-\-backup\fR[=\fICONTROL\fR]
747 Backup before removal. The \fICONTROL\fR argument, if supplied,
748 controls the backup policy. Its valid values are:
755 Make numbered backups.
757 .BR nil ", " existing
758 Make numbered backups if numbered backups exist, simple backups otherwise.
760 .BR never ", " simple
761 Always make simple backups
765 If \fICONTROL\fR is not given, the value is taken from the
767 environment variable. If it is not set, \fBexisting\fR is assumed.
770 \fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
771 Change to directory DIR.
773 \fB\-\-exclude\fR=\fIPATTERN\fR
774 Exclude files matching \fIPATTERN\fR, a
778 \fB\-\-exclude\-backups\fR
779 Exclude backup and lock files.
781 \fB\-\-exclude\-caches\fR
782 Exclude contents of directories containing file \fBCACHEDIR.TAG\fR,
783 except for the tag file itself.
785 \fB\-\-exclude\-caches\-all\fR
786 Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
788 \fB\-\-exclude\-caches\-under\fR
789 Exclude everything under directories containing \fBCACHEDIR.TAG\fR
791 \fB\-\-exclude\-ignore=\fIFILE\fR
792 Before dumping a directory, see if it contains \fIFILE\fR.
793 If so, read exclusion patterns from this file. The patterns affect
794 only the directory itself.
796 \fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
797 Same as \fB\-\-exclude\-ignore\fR, except that patterns from
798 \fIFILE\fR affect both the directory and all its subdirectories.
800 \fB\-\-exclude\-tag\fR=\fIFILE\fR
801 Exclude contents of directories containing \fIFILE\fR, except for
804 \fB\-\-exclude\-tag\-all\fR=\fIFILE\fR
805 Exclude directories containing \fIFILE\fR.
807 \fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
808 Exclude everything under directories containing \fIFILE\fR.
810 \fB\-\-exclude\-vcs\fR
811 Exclude version control system directories.
813 \fB\-\-exclude\-vcs\-ignores\fR
814 Exclude files that match patterns read from VCS-specific ignore
815 files. Supported files are:
818 .BR .bzrignore ", and"
821 \fB\-h\fR, \fB\-\-dereference\fR
822 Follow symlinks; archive and dump the files they point to.
824 \fB\-\-hard\-dereference\fR
825 Follow hard links; archive and dump the files they refer to.
827 \fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\fR
828 Begin at the given member in the archive.
830 \fB\-\-newer\-mtime\fR=\fIDATE\fR
831 Work on files whose data changed after the \fIDATE\fR. If \fIDATE\fR
832 starts with \fB/\fR or \fB.\fR it is taken to be a file name; the
833 mtime of that file is used as the date.
836 Disable the effect of the previous \fB\-\-null\fR option.
838 \fB\-\-no\-recursion\fR
839 Avoid descending automatically in directories.
841 \fB\-\-no\-unquote\fR
842 Do not unquote filenames read with \fB\-T\fR.
845 Instruct subsequent \fB\-T\fR options to read null-terminated names,
846 disable handling of the \fB\-C\fR option read from the file.
848 \fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
849 Only store files newer than DATE. If \fIDATE\fR starts with \fB/\fR
850 or \fB.\fR it is taken to be a file name; the ctime of that file is
853 \fB\-\-one\-file\-system\fR
854 Stay in local file system when creating archive.
856 \fB\-P\fR, \fB\-\-absolute\-names\fR
857 Don't strip leading slashes from file names when creating archives.
860 Recurse into directories (default).
862 \fB\-\-suffix\fR=\fISTRING\fR
863 Backup before removal, override usual suffix. Default suffix is \fB~\fR,
864 unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
866 \fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
867 Get names to extract or create from \fIFILE\fR.
870 Unquote filenames read with \fB\-T\fR (default).
872 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
873 Exclude files matching patterns listed in FILE.
874 .SS File name transformations
876 \fB\-\-strip\-components\fR=\fINUMBER\fR
877 Strip \fINUMBER\fR leading components from file names on extraction.
879 \fB\-\-transform\fR=\fIEXPRESSION\dR, \fB\-\-xform\fR=\fIEXPRESSION\fR
880 Use sed replace \fIEXPRESSION\fR to transform file names.
881 .SS File name matching options
882 These options affect both exclude and include patterns.
885 Patterns match file name start.
887 \fB\-\-ignore\-case\fR
890 \fB\-\-no\-anchored\fR
891 Patterns match after any \fB/\fR (default for exclusion).
893 \fB\-\-no\-ignore\-case\fR
894 Case sensitive matching (default).
896 \fB\-\-no\-wildcards\fR
897 Verbatim string matching.
899 \fB\-\-no\-wildcards\-match\-slash\fR
900 Wildcards do not match \fB/\fR.
903 Use wildcards (default for exclusion).
905 \fB\-\-wildcards\-match\-slash\fR
906 Wildcards match \fB/\fR (default for exclusion).
907 .SS Informative output
909 \fB\-\-checkpoint\fR[=\fIN\fR]
910 Display progress messages every \fIN\fRth record (default 10).
912 \fB\-\-checkpoint\-action\fR=\fIACTION\fR
913 Run \fIACTION\fR on each checkpoint.
916 Print file time to its full resolution.
918 \fB\-\-index\-file\fR=\fIFILE\fR
919 Send verbose output to \fIFILE\fR.
921 \fB\-l\fR, \fB\-\-check\-links\fR
922 Print a message if not all links are dumped.
924 \fB\-\-no\-quote\-chars\fR=\fISTRING\fR
925 Disable quoting for characters from \fISTRING\fR.
927 \fB\-\-quote\-chars\fR=\fISTRING\fR
928 Additionally quote characters from \fISTRING\fR.
930 \fB\-\-quoting\-style\fR=\fISTYLE\fR
931 Set quoting style for file and member names. Valid values for
942 \fB\-R\fR, \fB\-\-block\-number\fR
943 Show block number within archive with each message.
945 \fB\-\-show\-omitted\-dirs\fR
946 When listing or extracting, list each directory that does not match
949 \fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
950 Show file or archive names after transformation by \fB\-\-strip\fR and
951 \fB\-\-transform\fR options.
953 \fB\-\-totals\fR[=\fISIGNAL\fR]
954 Print total bytes after processing the archive. If \fISIGNAL\fR is
955 given, print total bytes when this signal is delivered. Allowed
962 The \fBSIG\fR prefix can be omitted.
965 Print file modification times in UTC.
967 \fB\-v\fR, \fB\-\-verbose\fR
968 Verbosely list files processed.
970 \fB\-\-warning\fR=\fIKEYWORD\fR
971 Enable or disable warning messages identified by \fIKEYWORD\fR. The
972 messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
973 and enabled otherwise.
975 Multiple \fB\-\-warning\fR messages accumulate.
977 Keywords controlling general \fBtar\fR operation:
981 Enable all warning messages. This is the default.
984 Disable all warning messages.
986 .B filename-with-nuls
987 "%s: file name read contains nul character"
990 "A lone zero block at %s"
992 Keywords applicable for \fBtar --create\fR:
995 "%s: contains a cache directory tag %s; %s"
998 "%s: File shrank by %s bytes; padding with zeros"
1001 "%s: file is on a different filesystem; not dumped"
1004 "%s: Unknown file type; file ignored"
1006 "%s: socket ignored"
1011 "%s: file is unchanged; not dumped"
1014 "%s: file is the archive; not dumped"
1017 "%s: File removed before we read it"
1020 "%s: file changed as we read it"
1022 Keywords applicable for \fBtar --extract\fR:
1025 "%s: implausibly old time stamp %s"
1027 "%s: time stamp %s is %s s in the future"
1030 "Extracting contiguous files as regular files"
1033 "Attempting extraction of symbolic links as hard links"
1036 "%s: Unknown file type '%c', extracted as normal file"
1039 "Current %s is newer or same age"
1042 "Ignoring unknown extended header keyword '%s'"
1044 .B decompress-program
1045 Controls verbose description of failures occurring when trying to run
1046 alternative decompressor programs. This warning is disabled by
1047 default (unless \fB\-\-verbose\fR is used). A common example of what
1048 you can get when using this warning is:
1051 $ \fBtar --warning=decompress-program -x -f archive.Z
1052 tar (child): cannot run compress: No such file or directory
1053 tar (child): trying gzip
1056 This means that \fBtar\fR first tried to decompress
1057 \fBarchive.Z\fR using \fBcompress\fR, and, when that
1058 failed, switched to \fBgzip\fR.
1061 "Record size = %lu blocks"
1063 Keywords controlling incremental extraction:
1066 "%s: Directory has been renamed from %s"
1068 "%s: Directory has been renamed"
1071 "%s: Directory is new"
1074 "%s: directory is on a different device: not purging"
1077 "Malformed dumpdir: 'X' never used"
1080 \fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
1081 Ask for confirmation for every action.
1082 .SS Compatibility options
1085 When creating, same as \fB\-\-old\-archive\fR. When extracting, same
1086 as \fB\-\-no\-same\-owner\fR.
1092 Suffix Units Byte Equivalent
1093 b Blocks \fISIZE\fR x 512
1094 B Kilobytes \fISIZE\fR x 1024
1096 G Gigabytes \fISIZE\fR x 1024^3
1097 K Kilobytes \fISIZE\fR x 1024
1098 k Kilobytes \fISIZE\fR x 1024
1099 M Megabytes \fISIZE\fR x 1024^2
1100 P Petabytes \fISIZE\fR x 1024^5
1101 T Terabytes \fISIZE\fR x 1024^4
1102 w Words \fISIZE\fR x 2
1106 Tar exit code indicates whether it was able to successfully perform
1107 the requested operation, and if not, what kind of error occurred.
1110 Successful termination.
1113 .I Some files differ.
1114 If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
1115 command line option, this means that some files in the archive differ
1116 from their disk counterparts. If tar was given one of the \fB\-\-create\fR,
1117 \fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
1118 that some files were changed while being archived and so the resulting
1119 archive does not contain the exact copy of the file set.
1123 This means that some fatal, unrecoverable error occurred.
1125 If a subprocess that had been invoked by
1127 exited with a nonzero exit code,
1129 itself exits with that code as well. This can happen, for example, if
1130 a compression option (e.g. \fB\-z\fR) was used and the external
1131 compressor program failed. Another example is
1133 failure during backup to a remote device.
1145 Complete \fBtar\fR manual: run
1149 info mode to read it.
1151 Online copies of \fBGNU tar\fR documentation in various formats can be
1155 .B http://www.gnu.org/software/tar/manual
1157 Report bugs to <bug\-tar@gnu.org>.
1159 Copyright \(co 2013 Free Software Foundation, Inc.
1162 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
1165 This is free software: you are free to change and redistribute it.
1166 There is NO WARRANTY, to the extent permitted by law.
1167 .\" Local variables:
1168 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
1169 .\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
1170 .\" time-stamp-format: "%:B %:d, %:y"
1171 .\" time-stamp-end: "\""
1172 .\" time-stamp-line-limit: 20