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 "August 16, 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\-\-skip\-old\-files
351 Don't replace existing files when extracting, silently skip over them.
353 \fB\-U\fR, \fB\-\-unlink\-first\fR
354 Remove each file prior to extracting over it.
356 \fB\-W\fR, \fB\-\-verify\fR
357 Verify the archive after writing it.
358 .SS Output stream selection
360 \fB\-\-ignore\-command\-error\fR
362 Ignore subprocess exit codes.
364 \fB\-\-no\-ignore\-command\-error\fR
365 Treat non-zero exit codes of children as error (default).
367 \fB\-O\fR, \fB\-\-to\-stdout\fR
368 Extract files to standard output.
370 \fB\-\-to\-command\fR=\fICOMMAND\fR
371 Pipe extracted files to \fICOMMAND\fR. The argument is the pathname
372 of an external program, optionally with command line arguments. The
373 program will be invoked and the contents of the file being extracted
374 supplied to it on its standard output. Additional data will be
375 supplied via the following environment variables:
379 Type of the file. It is a single letter with the following meaning:
391 Currently only regular files are supported.
394 File mode, an octal number.
397 The name of the file.
400 Name of the file as stored in the archive.
403 Name of the file owner.
406 Name of the file owner group.
409 Time of last access. It is a decimal number, representing seconds
410 since the Epoch. If the archive provides times with nanosecond
411 precision, the nanoseconds are appended to the timestamp after a
415 Time of last modification.
418 Time of last status change.
424 UID of the file owner.
427 GID of the file owner.
431 Additionally, the following variables contain information about
432 \fBtar\fR operation mode and the archive being processed:
435 GNU \fBtar\fR version number.
438 The name of the archive \fBtar\fR is processing.
440 .B TAR_BLOCKING_FACTOR
441 Current blocking factor, i.e. number of 512-byte blocks in a record.
444 Ordinal number of the volume \fBtar\fR is processing (set if
445 reading a multi-volume archive).
448 Format of the archive being processed. One of:
455 A short option (with a leading dash) describing the operation \fBtar\fR is
458 .SS Handling of file attributes
460 \fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
461 Preserve access times on dumped files, either by restoring the times
462 after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
463 not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
465 \fB\-\-delay\-directory\-restore\fR
466 Delay setting modification times and permissions of extracted
467 directories until the end of extraction. Use this option when
468 extracting from an archive which has unusual member ordering.
470 \fB\-\-group\fR=\fINAME\fR
471 Force \fINAME\fR as group for added files.
473 \fB\-\-mode\fR=\fICHANGES\fR
474 Force symbolic mode \fICHANGES\fR for added files.
476 \fB\-\-mtime\fR=\fIDATE-OR-FILE\fR
477 Set mtime for added files. \fIDATE-OR-FILE\fR is either a date/time
478 in almost arbitrary formate, or the name of an existing file. In the
479 latter case the mtime of that file will be used.
481 \fB\-m\fR, \fB\-\-touch\fR
482 Don't extract file modified time.
484 \fB\-\-no\-delay\-directory\-restore\fR
485 Cancel the effect of the prior \fB\-\-delay\-directory\-restore\fR option.
487 \fB\-\-no\-same\-owner\fR
488 Extract files as yourself (default for ordinary users).
490 \fB\-\-no\-same\-permissions\fR
491 Apply the user's umask when extracting permissions from the archive
492 (default for ordinary users).
494 \fB\-\-numeric\-owner\fR
495 Always use numbers for user/group names.
497 \fB\-\-owner\fR=\fINAME\fR
498 Force \fINAME\fR as owner for added files.
500 \fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
501 extract information about file permissions (default for superuser)
504 Same as both \fB\-p\fR and \fB\-s\fR.
506 \fB\-\-same\-owner\fR
507 Try extracting files with the same ownership as exists in the archive
508 (default for superuser).
510 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
511 Sort names to extract to match archive
513 \fB\-\-sort=\fIORDER\fR
514 When creating an archive, sort directory entries according to
515 \fIORDER\fR, which is one of
520 The default is \fB\-\-sort=none\fR, which stores archive members in
521 the same order as returned by the operating system.
523 Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
524 is uniform and reproducible.
526 Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
527 creating the archive and thus can considerably speed up archivation.
528 This sorting order is supported only if the underlying system provides
529 the necessary information.
530 .SS Device selection and switching
532 \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
533 Use archive file or device \fIARCHIVE\fR. If this option is not
534 given, \fBtar\fR will first examine the environment variable `TAPE'.
535 If it is set, its value will be used as the archive name. Otherwise,
536 \fBtar\fR will assume the compiled-in default. The default
537 value can be inspected either using the
538 .B \-\-show\-defaults
539 option, or at the end of the \fBtar \-\-help\fR output.
541 An archive name that has a colon in it specifies a file or device on a
542 remote machine. The part before the colon is taken as the machine
543 name or IP address, and the part after it as the file or device
547 --file=remotehost:/dev/sr0
550 An optional username can be prefixed to the hostname, placing a \fB@\fR
553 By default, the remote host is accessed via the
555 command. Nowadays it is common to use
557 instead. You can do so by giving the following command line option:
560 --rsh-command=/usr/bin/ssh
563 The remote machine should have the
565 command installed. If its pathname does not match \fBtar\fR's
566 default, you can inform \fBtar\fR about the correct pathname using the
570 \fB\-\-force\-local\fR
571 Archive file is local even if it has a colon.
573 \fB\-\fRF, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
574 Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The
575 command can include arguments. When started, it will inherit \fBtar\fR's
576 environment plus the following variables:
580 GNU \fBtar\fR version number.
583 The name of the archive \fBtar\fR is processing.
585 .B TAR_BLOCKING_FACTOR
586 Current blocking factor, i.e. number of 512-byte blocks in a record.
589 Ordinal number of the volume \fBtar\fR is processing (set if
590 reading a multi-volume archive).
593 Format of the archive being processed. One of:
601 A short option (with a leading dash) describing the operation \fBtar\fR is
605 File descriptor which can be used to communicate the new volume name
611 If the info script fails, \fBtar\fR exits; otherwise, it begins writing
615 \fB\-L\fR, \fB\-\-tape\-length\fR=\fN\fR
616 Change tape after writing \fIN\fRx1024 bytes. If \fIN\fR is followed
617 by a size suffix (see the subsection
619 below), the suffix specifies the multiplicative factor to be used
625 \fB\-M\fR, \fB\-\-multi\-volume\fR
626 Create/list/extract multi-volume archive.
628 \fB\-\-rmt\-command\fR=\fICOMMAND\fR
629 Use \fICOMMAND\fR instead of \fBrmt\fR when accessing remote
630 archives. See the description of the
634 \fB\-\-rsh\-command\fR=\fICOMMAND\fR
635 Use \fICOMMAND\fR instead of \fBrsh\fR when accessing remote
636 archives. See the description of the
640 \fB\-\-volno\-file\fR=\fIFILE\fR
641 When this option is used in conjunction with
642 .BR \-\-multi\-volume ,
644 will keep track of which volume of a multi-volume archive it is
645 working in \fIFILE\fR.
648 \fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
649 Set record size to \fIBLOCKS\fRx\fB512\fR bytes.
651 \fB\-B\fR, \fB\-\-read\-full\-records\fR
652 When listing or extracting, accept incomplete input records after
655 \fB\-i\fR, \fB\-\-ignore\-zeros\fR
656 Ignore zeroed blocks in archive. Normally two consecutive 512-blocks
657 filled with zeroes mean EOF and tar stops reading after encountering
658 them. This option instructs it to read further and is useful when
659 reading archives created with the \fB\-A\fR option.
661 \fB\-\-record\-size\fR=\fINUMBER\fR
662 Set record size. \fINUMBER\fR is the number of bytes per record. It
663 must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
664 suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
666 .BR "Size suffixes" ,
667 for a list of valid suffixes.
668 .SS Archive format selection
670 \fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
671 Create archive of the given format. Valid formats are:
675 GNU tar 1.13.x format
678 GNU format as per tar <= 1.12.
680 \fBpax\fR, \fBposix\fR
681 POSIX 1003.1-2001 (pax) format.
684 POSIX 1003.1-1988 (ustar) format.
690 \fB\-\-old\-archive\fR, \fB\-\-portability\fR
691 Same as \fB\-\-format=v7\fR.
693 \fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
694 Control pax keywords when creating \fBPAX\fR archives (\fB\-H
695 pax\fR). This option is equivalent to the \fB\-o\fR option of the
699 Same as \fB\-\-format=posix\fR.
701 \fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
702 Create archive with volume name \fITEXT\fR. If listing or extracting,
703 use \fITEXT\fR as a globbing pattern for volume name.
704 .SS Compression options
706 \fB\-a\fR, \fB\-\-auto\-compress\fR
707 Use archive suffix to determine the compression program.
709 \fB\-\fRI, \fB\-\-use\-compress\-program\fI=\fICOMMAND\fR
710 Filter data through \fICOMMAND\fR. It must accept the \fB\-d\fR
711 option, for decompression. The argument can contain command line
714 \fB\-j\fR, \fB\-\-bzip2\fR
715 Filter the archive through
718 \fB\-J\fR, \fB\-\-xz\fR
719 Filter the archive through
723 Filter the archive through
727 Filter the archive through
731 Filter the archive through
734 \fB\-\-no\-auto\-compress\fR
735 Do not use archive suffix to determine the compression program.
737 \fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
738 Filter the archive through
741 \fB\-\fRZ, \fB\-\-compress\fR, \fB\-\-uncompress\fR
742 Filter the archive through
744 .SS Local file selection
746 \fB\-\-add\-file\fR=\fIFILE\fR
747 Add \fIFILE\fR to the archive (useful if its name starts with a dash).
749 \fB\-\-backup\fR[=\fICONTROL\fR]
750 Backup before removal. The \fICONTROL\fR argument, if supplied,
751 controls the backup policy. Its valid values are:
758 Make numbered backups.
760 .BR nil ", " existing
761 Make numbered backups if numbered backups exist, simple backups otherwise.
763 .BR never ", " simple
764 Always make simple backups
768 If \fICONTROL\fR is not given, the value is taken from the
770 environment variable. If it is not set, \fBexisting\fR is assumed.
773 \fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
774 Change to directory DIR.
776 \fB\-\-exclude\fR=\fIPATTERN\fR
777 Exclude files matching \fIPATTERN\fR, a
781 \fB\-\-exclude\-backups\fR
782 Exclude backup and lock files.
784 \fB\-\-exclude\-caches\fR
785 Exclude contents of directories containing file \fBCACHEDIR.TAG\fR,
786 except for the tag file itself.
788 \fB\-\-exclude\-caches\-all\fR
789 Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
791 \fB\-\-exclude\-caches\-under\fR
792 Exclude everything under directories containing \fBCACHEDIR.TAG\fR
794 \fB\-\-exclude\-ignore=\fIFILE\fR
795 Before dumping a directory, see if it contains \fIFILE\fR.
796 If so, read exclusion patterns from this file. The patterns affect
797 only the directory itself.
799 \fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
800 Same as \fB\-\-exclude\-ignore\fR, except that patterns from
801 \fIFILE\fR affect both the directory and all its subdirectories.
803 \fB\-\-exclude\-tag\fR=\fIFILE\fR
804 Exclude contents of directories containing \fIFILE\fR, except for
807 \fB\-\-exclude\-tag\-all\fR=\fIFILE\fR
808 Exclude directories containing \fIFILE\fR.
810 \fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
811 Exclude everything under directories containing \fIFILE\fR.
813 \fB\-\-exclude\-vcs\fR
814 Exclude version control system directories.
816 \fB\-\-exclude\-vcs\-ignores\fR
817 Exclude files that match patterns read from VCS-specific ignore
818 files. Supported files are:
821 .BR .bzrignore ", and"
824 \fB\-h\fR, \fB\-\-dereference\fR
825 Follow symlinks; archive and dump the files they point to.
827 \fB\-\-hard\-dereference\fR
828 Follow hard links; archive and dump the files they refer to.
830 \fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\fR
831 Begin at the given member in the archive.
833 \fB\-\-newer\-mtime\fR=\fIDATE\fR
834 Work on files whose data changed after the \fIDATE\fR. If \fIDATE\fR
835 starts with \fB/\fR or \fB.\fR it is taken to be a file name; the
836 mtime of that file is used as the date.
839 Disable the effect of the previous \fB\-\-null\fR option.
841 \fB\-\-no\-recursion\fR
842 Avoid descending automatically in directories.
844 \fB\-\-no\-unquote\fR
845 Do not unquote input file or member names.
848 Instruct subsequent \fB\-T\fR options to read null-terminated names,
849 disable handling of the \fB\-C\fR option read from the file.
851 \fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
852 Only store files newer than DATE. If \fIDATE\fR starts with \fB/\fR
853 or \fB.\fR it is taken to be a file name; the ctime of that file is
856 \fB\-\-one\-file\-system\fR
857 Stay in local file system when creating archive.
859 \fB\-P\fR, \fB\-\-absolute\-names\fR
860 Don't strip leading slashes from file names when creating archives.
863 Recurse into directories (default).
865 \fB\-\-suffix\fR=\fISTRING\fR
866 Backup before removal, override usual suffix. Default suffix is \fB~\fR,
867 unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
869 \fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
870 Get names to extract or create from \fIFILE\fR.
873 Unquote file or member names (default).
875 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
876 Exclude files matching patterns listed in FILE.
877 .SS File name transformations
879 \fB\-\-strip\-components\fR=\fINUMBER\fR
880 Strip \fINUMBER\fR leading components from file names on extraction.
882 \fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR
883 Use sed replace \fIEXPRESSION\fR to transform file names.
884 .SS File name matching options
885 These options affect both exclude and include patterns.
888 Patterns match file name start.
890 \fB\-\-ignore\-case\fR
893 \fB\-\-no\-anchored\fR
894 Patterns match after any \fB/\fR (default for exclusion).
896 \fB\-\-no\-ignore\-case\fR
897 Case sensitive matching (default).
899 \fB\-\-no\-wildcards\fR
900 Verbatim string matching.
902 \fB\-\-no\-wildcards\-match\-slash\fR
903 Wildcards do not match \fB/\fR.
906 Use wildcards (default for exclusion).
908 \fB\-\-wildcards\-match\-slash\fR
909 Wildcards match \fB/\fR (default for exclusion).
910 .SS Informative output
912 \fB\-\-checkpoint\fR[=\fIN\fR]
913 Display progress messages every \fIN\fRth record (default 10).
915 \fB\-\-checkpoint\-action\fR=\fIACTION\fR
916 Run \fIACTION\fR on each checkpoint.
919 Print file time to its full resolution.
921 \fB\-\-index\-file\fR=\fIFILE\fR
922 Send verbose output to \fIFILE\fR.
924 \fB\-l\fR, \fB\-\-check\-links\fR
925 Print a message if not all links are dumped.
927 \fB\-\-no\-quote\-chars\fR=\fISTRING\fR
928 Disable quoting for characters from \fISTRING\fR.
930 \fB\-\-quote\-chars\fR=\fISTRING\fR
931 Additionally quote characters from \fISTRING\fR.
933 \fB\-\-quoting\-style\fR=\fISTYLE\fR
934 Set quoting style for file and member names. Valid values for
945 \fB\-R\fR, \fB\-\-block\-number\fR
946 Show block number within archive with each message.
948 \fB\-\-show\-omitted\-dirs\fR
949 When listing or extracting, list each directory that does not match
952 \fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
953 Show file or archive names after transformation by \fB\-\-strip\fR and
954 \fB\-\-transform\fR options.
956 \fB\-\-totals\fR[=\fISIGNAL\fR]
957 Print total bytes after processing the archive. If \fISIGNAL\fR is
958 given, print total bytes when this signal is delivered. Allowed
965 The \fBSIG\fR prefix can be omitted.
968 Print file modification times in UTC.
970 \fB\-v\fR, \fB\-\-verbose\fR
971 Verbosely list files processed.
973 \fB\-\-warning\fR=\fIKEYWORD\fR
974 Enable or disable warning messages identified by \fIKEYWORD\fR. The
975 messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
976 and enabled otherwise.
978 Multiple \fB\-\-warning\fR messages accumulate.
980 Keywords controlling general \fBtar\fR operation:
984 Enable all warning messages. This is the default.
987 Disable all warning messages.
989 .B filename-with-nuls
990 "%s: file name read contains nul character"
993 "A lone zero block at %s"
995 Keywords applicable for \fBtar --create\fR:
998 "%s: contains a cache directory tag %s; %s"
1001 "%s: File shrank by %s bytes; padding with zeros"
1004 "%s: file is on a different filesystem; not dumped"
1007 "%s: Unknown file type; file ignored"
1009 "%s: socket ignored"
1014 "%s: file is unchanged; not dumped"
1017 "%s: file is the archive; not dumped"
1020 "%s: File removed before we read it"
1023 "%s: file changed as we read it"
1025 Keywords applicable for \fBtar --extract\fR:
1028 "%s: skipping existing file"
1031 "%s: implausibly old time stamp %s"
1033 "%s: time stamp %s is %s s in the future"
1036 "Extracting contiguous files as regular files"
1039 "Attempting extraction of symbolic links as hard links"
1042 "%s: Unknown file type '%c', extracted as normal file"
1045 "Current %s is newer or same age"
1048 "Ignoring unknown extended header keyword '%s'"
1050 .B decompress-program
1051 Controls verbose description of failures occurring when trying to run
1052 alternative decompressor programs. This warning is disabled by
1053 default (unless \fB\-\-verbose\fR is used). A common example of what
1054 you can get when using this warning is:
1057 $ \fBtar --warning=decompress-program -x -f archive.Z
1058 tar (child): cannot run compress: No such file or directory
1059 tar (child): trying gzip
1062 This means that \fBtar\fR first tried to decompress
1063 \fBarchive.Z\fR using \fBcompress\fR, and, when that
1064 failed, switched to \fBgzip\fR.
1067 "Record size = %lu blocks"
1069 Keywords controlling incremental extraction:
1072 "%s: Directory has been renamed from %s"
1074 "%s: Directory has been renamed"
1077 "%s: Directory is new"
1080 "%s: directory is on a different device: not purging"
1083 "Malformed dumpdir: 'X' never used"
1086 \fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
1087 Ask for confirmation for every action.
1088 .SS Compatibility options
1091 When creating, same as \fB\-\-old\-archive\fR. When extracting, same
1092 as \fB\-\-no\-same\-owner\fR.
1098 Suffix Units Byte Equivalent
1099 b Blocks \fISIZE\fR x 512
1100 B Kilobytes \fISIZE\fR x 1024
1102 G Gigabytes \fISIZE\fR x 1024^3
1103 K Kilobytes \fISIZE\fR x 1024
1104 k Kilobytes \fISIZE\fR x 1024
1105 M Megabytes \fISIZE\fR x 1024^2
1106 P Petabytes \fISIZE\fR x 1024^5
1107 T Terabytes \fISIZE\fR x 1024^4
1108 w Words \fISIZE\fR x 2
1112 Tar exit code indicates whether it was able to successfully perform
1113 the requested operation, and if not, what kind of error occurred.
1116 Successful termination.
1119 .I Some files differ.
1120 If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
1121 command line option, this means that some files in the archive differ
1122 from their disk counterparts. If tar was given one of the \fB\-\-create\fR,
1123 \fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
1124 that some files were changed while being archived and so the resulting
1125 archive does not contain the exact copy of the file set.
1129 This means that some fatal, unrecoverable error occurred.
1131 If a subprocess that had been invoked by
1133 exited with a nonzero exit code,
1135 itself exits with that code as well. This can happen, for example, if
1136 a compression option (e.g. \fB\-z\fR) was used and the external
1137 compressor program failed. Another example is
1139 failure during backup to a remote device.
1151 Complete \fBtar\fR manual: run
1155 info mode to read it.
1157 Online copies of \fBGNU tar\fR documentation in various formats can be
1161 .B http://www.gnu.org/software/tar/manual
1163 Report bugs to <bug\-tar@gnu.org>.
1165 Copyright \(co 2013 Free Software Foundation, Inc.
1168 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
1171 This is free software: you are free to change and redistribute it.
1172 There is NO WARRANTY, to the extent permitted by law.
1173 .\" Local variables:
1174 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
1175 .\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
1176 .\" time-stamp-format: "%:B %:d, %:y"
1177 .\" time-stamp-end: "\""
1178 .\" time-stamp-line-limit: 20