1 .\" This file is part of GNU tar. -*- nroff -*-
2 .\" Copyright 2013-2014, 2016 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 "March 23, 2016" "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\fR} [\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\fR) 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\fR).
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\-\-hole\-detection\fR=\fIMETHOD\fR
263 Use \fIMETHOD\fR to detect holes in sparse files. This option implies
264 \fB\-\-sparse\fR. Valid values for \fIMETHOD\fR are \fBseek\fR and
265 \fBraw\fR. Default is \fBseek\fR with fallback to \fBraw\fR when not
268 \fB\-G\fR, \fB\-\-incremental\fR
269 Handle old GNU-format incremental backups.
271 \fB\-\-ignore\-failed\-read\fR
272 Do not exit with nonzero on unreadable files.
274 \fB\-\-level\fR=\fINUMBER\fR
275 Set dump level for created listed-incremental archive. Currently only
276 \fB\-\-level=0\fR is meaningful: it instructs \fBtar\fR to truncate
277 the snapshot file before dumping, thereby forcing a level 0 dump.
279 \fB\-n\fR, \fB\-\-seek\fR
280 Assume the archive is seekable. Normally \fBtar\fR determines
281 automatically whether the archive can be seeked or not. This option
282 is intended for use in cases when such recognition fails. It takes
283 effect only if the archive is open for reading (e.g. with
289 \fB\-\-no\-check\-device\fR
290 Do not check device numbers when creating incremental archives.
293 Assume the archive is not seekable.
295 \fB\-\-occurrence\fR[=\fIN\fR]
296 Process only the \fIN\fRth occurrence of each file in the
297 archive. This option is valid only when used with one of the
298 following subcommands: \fB\-\-delete\fR, \fB\-\-diff\fR,
299 \fB\-\-extract\fR or \fB\-\-list\fR and when a list of files is given
300 either on the command line or via the \fB\-T\fR option. The default
304 Disable the use of some potentially harmful options.
306 \fB\-\-sparse\-version\fR=\fIMAJOR\fR[.\fIMINOR\fR]
307 Set version of the sparse format to use (implies \fB\-\-sparse\fR).
310 Valid argument values are
314 For a detailed discussion of sparse formats, refer to the \fBGNU Tar
315 Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR". Using \fBinfo\fR
316 reader, it can be accessed running the following command:
317 .BR "info tar 'Sparse Formats'" .
319 \fB\-S\fR, \fB\-\-sparse\fR
320 Handle sparse files efficiently. Some files in the file system may
321 have segments which were actually never written (quite often these are
322 database files created by such systems as \fBDBM\fR). When given this
323 option, \fBtar\fR attempts to determine if the file is sparse prior to
324 archiving it, and if so, to reduce the resulting archive size by not
325 dumping empty parts of the file.
326 .SS Overwrite control
327 These options control \fBtar\fR actions when extracting a file over
328 an existing copy on disk.
330 \fB\-k\fR, \fB\-\-keep\-old\-files\fR
331 Don't replace existing files when extracting.
333 \fB\-\-keep\-newer\-files\fR
334 Don't replace existing files that are newer than their archive copies.
336 \fB\-\-no\-overwrite\-dir\fR
337 Preserve metadata of existing directories.
339 \fB\-\-one\-top\-level\fR[\fB=\fIDIR\fR]
340 Extract all files into \fIDIR\fR, or, if used without argument, into a
341 subdirectory named by the base name of the archive (minus standard
342 compression suffixes recognizable by \fB\-\-auto\-compress).
345 Overwrite existing files when extracting.
347 \fB\-\-overwrite\-dir\fR
348 Overwrite metadata of existing directories when extracting (default).
350 \fB\-\-recursive\-unlink\fR
351 Recursively remove all files in the directory prior to extracting it.
353 \fB\-\-remove\-files\fR
354 Remove files from disk after adding them to the archive.
356 \fB\-\-skip\-old\-files
357 Don't replace existing files when extracting, silently skip over them.
359 \fB\-U\fR, \fB\-\-unlink\-first\fR
360 Remove each file prior to extracting over it.
362 \fB\-W\fR, \fB\-\-verify\fR
363 Verify the archive after writing it.
364 .SS Output stream selection
366 \fB\-\-ignore\-command\-error\fR
368 Ignore subprocess exit codes.
370 \fB\-\-no\-ignore\-command\-error\fR
371 Treat non-zero exit codes of children as error (default).
373 \fB\-O\fR, \fB\-\-to\-stdout\fR
374 Extract files to standard output.
376 \fB\-\-to\-command\fR=\fICOMMAND\fR
377 Pipe extracted files to \fICOMMAND\fR. The argument is the pathname
378 of an external program, optionally with command line arguments. The
379 program will be invoked and the contents of the file being extracted
380 supplied to it on its standard output. Additional data will be
381 supplied via the following environment variables:
385 Type of the file. It is a single letter with the following meaning:
397 Currently only regular files are supported.
400 File mode, an octal number.
403 The name of the file.
406 Name of the file as stored in the archive.
409 Name of the file owner.
412 Name of the file owner group.
415 Time of last access. It is a decimal number, representing seconds
416 since the Epoch. If the archive provides times with nanosecond
417 precision, the nanoseconds are appended to the timestamp after a
421 Time of last modification.
424 Time of last status change.
430 UID of the file owner.
433 GID of the file owner.
437 Additionally, the following variables contain information about
438 \fBtar\fR operation mode and the archive being processed:
441 GNU \fBtar\fR version number.
444 The name of the archive \fBtar\fR is processing.
446 .B TAR_BLOCKING_FACTOR
447 Current blocking factor, i.e. number of 512-byte blocks in a record.
450 Ordinal number of the volume \fBtar\fR is processing (set if
451 reading a multi-volume archive).
454 Format of the archive being processed. One of:
461 A short option (with a leading dash) describing the operation \fBtar\fR is
464 .SS Handling of file attributes
466 \fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
467 Preserve access times on dumped files, either by restoring the times
468 after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
469 not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
471 \fB\-\-delay\-directory\-restore\fR
472 Delay setting modification times and permissions of extracted
473 directories until the end of extraction. Use this option when
474 extracting from an archive which has unusual member ordering.
476 \fB\-\-group\fR=\fINAME\fR[:\fIGID\fR]
477 Force \fINAME\fR as group for added files. If \fIGID\fR is not
478 supplied, \fINAME\fR can be either a user name or numeric GID. In
479 this case the missing part (GID or name) will be inferred from the
480 current host's group database.
482 When used with \fB\-\-group\-map\fR=\fIFILE\fR, affects only those
483 files whose owner group is not listed in \fIFILE\fR.
485 \fB\-\-group\-map\fR=\fIFILE\fR
486 Read group translation map from \fIFILE\fR. Empty lines are ignored.
487 Comments are introduced with \fB#\fR sign and extend to the end of line.
488 Each non-empty line in \fIFILE\fR defines translation for a single
489 group. It must consist of two fields, delimited by any amount of whitespace:
492 \fIOLDGRP\fR \fINEWGRP\fR[\fB:\fINEWGID\fR]
495 \fIOLDGRP\fR is either a valid group name or a GID prefixed with
496 \fB+\fR. Unless \fINEWGID\fR is supplied, \fINEWGRP\fR must also be
497 either a valid group name or a \fB+\fIGID\fR. Otherwise, both
498 \fINEWGRP\fR and \fINEWGID\fR need not be listed in the system group
501 As a result, each input file with owner group \fIOLDGRP\fR will be
502 stored in archive with owner group \fINEWGRP\fR and GID \fINEWGID\fR.
504 \fB\-\-mode\fR=\fICHANGES\fR
505 Force symbolic mode \fICHANGES\fR for added files.
507 \fB\-\-mtime\fR=\fIDATE-OR-FILE\fR
508 Set mtime for added files. \fIDATE-OR-FILE\fR is either a date/time
509 in almost arbitrary format, or the name of an existing file. In the
510 latter case the mtime of that file will be used.
512 \fB\-m\fR, \fB\-\-touch\fR
513 Don't extract file modified time.
515 \fB\-\-no\-delay\-directory\-restore\fR
516 Cancel the effect of the prior \fB\-\-delay\-directory\-restore\fR option.
518 \fB\-\-no\-same\-owner\fR
519 Extract files as yourself (default for ordinary users).
521 \fB\-\-no\-same\-permissions\fR
522 Apply the user's umask when extracting permissions from the archive
523 (default for ordinary users).
525 \fB\-\-numeric\-owner\fR
526 Always use numbers for user/group names.
528 \fB\-\-owner\fR=\fINAME\fR[:\fIUID\fR]
529 Force \fINAME\fR as owner for added files. If \fIUID\fR is not
530 supplied, \fINAME\fR can be either a user name or numeric UID. In
531 this case the missing part (UID or name) will be inferred from the
532 current host's user database.
534 When used with \fB\-\-owner\-map\fR=\fIFILE\fR, affects only those
535 files whose owner is not listed in \fIFILE\fR.
537 \fB\-\-owner\-map\fR=\fIFILE\fR
538 Read owner translation map from \fIFILE\fR. Empty lines are ignored.
539 Comments are introduced with \fB#\fR sign and extend to the end of line.
540 Each non-empty line in \fIFILE\fR defines translation for a single
541 UID. It must consist of two fields, delimited by any amount of whitespace:
544 \fIOLDUSR\fR \fINEWUSR\fR[\fB:\fINEWUID\fR]
547 \fIOLDUSR\fR is either a valid user name or a UID prefixed with
548 \fB+\fR. Unless \fINEWUID\fR is supplied, \fINEWUSR\fR must also be
549 either a valid user name or a \fB+\fIUID\fR. Otherwise, both
550 \fINEWUSR\fR and \fINEWUID\fR need not be listed in the system user
553 As a result, each input file owned by \fIOLDUSR\fR will be
554 stored in archive with owner name \fINEWUSR\fR and UID \fINEWUID\fR.
556 \fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
557 extract information about file permissions (default for superuser)
560 Same as both \fB\-p\fR and \fB\-s\fR.
562 \fB\-\-same\-owner\fR
563 Try extracting files with the same ownership as exists in the archive
564 (default for superuser).
566 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
567 Sort names to extract to match archive
569 \fB\-\-sort=\fIORDER\fR
570 When creating an archive, sort directory entries according to
571 \fIORDER\fR, which is one of
576 The default is \fB\-\-sort=none\fR, which stores archive members in
577 the same order as returned by the operating system.
579 Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
580 is uniform and reproducible.
582 Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
583 creating the archive and thus can considerably speed up archivation.
584 This sorting order is supported only if the underlying system provides
585 the necessary information.
586 .SS Extended file attributes
589 Enable POSIX ACLs support.
592 Disable POSIX ACLs support.
595 Enable SELinux context support.
598 Disable SELinux context support.
601 Enable extended attributes support.
604 Disable extended attributes support.
606 .BI \-\-xattrs\-exclude= PATTERN
607 Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a POSIX
608 regular expression, e.g. \fB\-\-xattrs\-exclude='^user\.'\fR, to exclude
609 attributes from the user namespace.
611 .BI \-\-xattrs\-include= PATTERN
612 Specify the include pattern for xattr keys. \fIPATTERN\fR is a POSIX
614 .SS Device selection and switching
616 \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
617 Use archive file or device \fIARCHIVE\fR. If this option is not
618 given, \fBtar\fR will first examine the environment variable `TAPE'.
619 If it is set, its value will be used as the archive name. Otherwise,
620 \fBtar\fR will assume the compiled-in default. The default
621 value can be inspected either using the
622 .B \-\-show\-defaults
623 option, or at the end of the \fBtar \-\-help\fR output.
625 An archive name that has a colon in it specifies a file or device on a
626 remote machine. The part before the colon is taken as the machine
627 name or IP address, and the part after it as the file or device
631 --file=remotehost:/dev/sr0
634 An optional username can be prefixed to the hostname, placing a \fB@\fR
637 By default, the remote host is accessed via the
639 command. Nowadays it is common to use
641 instead. You can do so by giving the following command line option:
644 --rsh-command=/usr/bin/ssh
647 The remote machine should have the
649 command installed. If its pathname does not match \fBtar\fR's
650 default, you can inform \fBtar\fR about the correct pathname using the
654 \fB\-\-force\-local\fR
655 Archive file is local even if it has a colon.
657 \fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
658 Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The
659 command can include arguments. When started, it will inherit \fBtar\fR's
660 environment plus the following variables:
664 GNU \fBtar\fR version number.
667 The name of the archive \fBtar\fR is processing.
669 .B TAR_BLOCKING_FACTOR
670 Current blocking factor, i.e. number of 512-byte blocks in a record.
673 Ordinal number of the volume \fBtar\fR is processing (set if
674 reading a multi-volume archive).
677 Format of the archive being processed. One of:
685 A short option (with a leading dash) describing the operation \fBtar\fR is
689 File descriptor which can be used to communicate the new volume name
695 If the info script fails, \fBtar\fR exits; otherwise, it begins writing
699 \fB\-L\fR, \fB\-\-tape\-length\fR=\fIN\fR
700 Change tape after writing \fIN\fRx1024 bytes. If \fIN\fR is followed
701 by a size suffix (see the subsection
703 below), the suffix specifies the multiplicative factor to be used
709 \fB\-M\fR, \fB\-\-multi\-volume\fR
710 Create/list/extract multi-volume archive.
712 \fB\-\-rmt\-command\fR=\fICOMMAND\fR
713 Use \fICOMMAND\fR instead of \fBrmt\fR when accessing remote
714 archives. See the description of the
718 \fB\-\-rsh\-command\fR=\fICOMMAND\fR
719 Use \fICOMMAND\fR instead of \fBrsh\fR when accessing remote
720 archives. See the description of the
724 \fB\-\-volno\-file\fR=\fIFILE\fR
725 When this option is used in conjunction with
726 .BR \-\-multi\-volume ,
728 will keep track of which volume of a multi-volume archive it is
729 working in \fIFILE\fR.
732 \fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
733 Set record size to \fIBLOCKS\fRx\fB512\fR bytes.
735 \fB\-B\fR, \fB\-\-read\-full\-records\fR
736 When listing or extracting, accept incomplete input records after
739 \fB\-i\fR, \fB\-\-ignore\-zeros\fR
740 Ignore zeroed blocks in archive. Normally two consecutive 512-blocks
741 filled with zeroes mean EOF and tar stops reading after encountering
742 them. This option instructs it to read further and is useful when
743 reading archives created with the \fB\-A\fR option.
745 \fB\-\-record\-size\fR=\fINUMBER\fR
746 Set record size. \fINUMBER\fR is the number of bytes per record. It
747 must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
748 suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
750 .BR "Size suffixes" ,
751 for a list of valid suffixes.
752 .SS Archive format selection
754 \fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
755 Create archive of the given format. Valid formats are:
759 GNU tar 1.13.x format
762 GNU format as per tar <= 1.12.
764 \fBpax\fR, \fBposix\fR
765 POSIX 1003.1-2001 (pax) format.
768 POSIX 1003.1-1988 (ustar) format.
774 \fB\-\-old\-archive\fR, \fB\-\-portability\fR
775 Same as \fB\-\-format=v7\fR.
777 \fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
778 Control pax keywords when creating \fBPAX\fR archives (\fB\-H
779 pax\fR). This option is equivalent to the \fB\-o\fR option of the
783 Same as \fB\-\-format=posix\fR.
785 \fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
786 Create archive with volume name \fITEXT\fR. If listing or extracting,
787 use \fITEXT\fR as a globbing pattern for volume name.
788 .SS Compression options
790 \fB\-a\fR, \fB\-\-auto\-compress\fR
791 Use archive suffix to determine the compression program.
793 \fB\-I\fR, \fB\-\-use\-compress\-program\fI=\fICOMMAND\fR
794 Filter data through \fICOMMAND\fR. It must accept the \fB\-d\fR
795 option, for decompression. The argument can contain command line
798 \fB\-j\fR, \fB\-\-bzip2\fR
799 Filter the archive through
802 \fB\-J\fR, \fB\-\-xz\fR
803 Filter the archive through
807 Filter the archive through
811 Filter the archive through
815 Filter the archive through
818 \fB\-\-no\-auto\-compress\fR
819 Do not use archive suffix to determine the compression program.
821 \fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
822 Filter the archive through
825 \fB\-Z\fR, \fB\-\-compress\fR, \fB\-\-uncompress\fR
826 Filter the archive through
828 .SS Local file selection
830 \fB\-\-add\-file\fR=\fIFILE\fR
831 Add \fIFILE\fR to the archive (useful if its name starts with a dash).
833 \fB\-\-backup\fR[=\fICONTROL\fR]
834 Backup before removal. The \fICONTROL\fR argument, if supplied,
835 controls the backup policy. Its valid values are:
842 Make numbered backups.
844 .BR nil ", " existing
845 Make numbered backups if numbered backups exist, simple backups otherwise.
847 .BR never ", " simple
848 Always make simple backups
852 If \fICONTROL\fR is not given, the value is taken from the
854 environment variable. If it is not set, \fBexisting\fR is assumed.
857 \fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
858 Change to \fIDIR\fR before performing any operations. This option is
859 order-sensitive, i.e. it affects all options that follow.
861 \fB\-\-exclude\fR=\fIPATTERN\fR
862 Exclude files matching \fIPATTERN\fR, a
866 \fB\-\-exclude\-backups\fR
867 Exclude backup and lock files.
869 \fB\-\-exclude\-caches\fR
870 Exclude contents of directories containing file \fBCACHEDIR.TAG\fR,
871 except for the tag file itself.
873 \fB\-\-exclude\-caches\-all\fR
874 Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
876 \fB\-\-exclude\-caches\-under\fR
877 Exclude everything under directories containing \fBCACHEDIR.TAG\fR
879 \fB\-\-exclude\-ignore=\fIFILE\fR
880 Before dumping a directory, see if it contains \fIFILE\fR.
881 If so, read exclusion patterns from this file. The patterns affect
882 only the directory itself.
884 \fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
885 Same as \fB\-\-exclude\-ignore\fR, except that patterns from
886 \fIFILE\fR affect both the directory and all its subdirectories.
888 \fB\-\-exclude\-tag\fR=\fIFILE\fR
889 Exclude contents of directories containing \fIFILE\fR, except for
892 \fB\-\-exclude\-tag\-all\fR=\fIFILE\fR
893 Exclude directories containing \fIFILE\fR.
895 \fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
896 Exclude everything under directories containing \fIFILE\fR.
898 \fB\-\-exclude\-vcs\fR
899 Exclude version control system directories.
901 \fB\-\-exclude\-vcs\-ignores\fR
902 Exclude files that match patterns read from VCS-specific ignore
903 files. Supported files are:
906 .BR .bzrignore ", and"
909 \fB\-h\fR, \fB\-\-dereference\fR
910 Follow symlinks; archive and dump the files they point to.
912 \fB\-\-hard\-dereference\fR
913 Follow hard links; archive and dump the files they refer to.
915 \fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\fR
916 Begin at the given member in the archive.
918 \fB\-\-newer\-mtime\fR=\fIDATE\fR
919 Work on files whose data changed after the \fIDATE\fR. If \fIDATE\fR
920 starts with \fB/\fR or \fB.\fR it is taken to be a file name; the
921 mtime of that file is used as the date.
924 Disable the effect of the previous \fB\-\-null\fR option.
926 \fB\-\-no\-recursion\fR
927 Avoid descending automatically in directories.
929 \fB\-\-no\-unquote\fR
930 Do not unquote input file or member names.
932 \fB\-\-no\-verbatim\-files\-from\fR
933 Treat each line read from a file list as if it were supplied in the
934 command line. I.e., leading and trailing whitespace is removed and,
935 if the resulting string begins with a dash, it is treated as \fBtar\fR
938 This is the default behavior. The \fB\-\-no\-verbatim\-files\-from\fR
939 option is provided as a way to restore it after
940 \fB\-\-verbatim\-files\-from\fR option.
942 This option is positional: it affects all \fB\-\-files\-from\fR
943 options that occur after it in, until \fB\-\-verbatim\-files\-from\fR
944 option or end of line, whichever occurs first.
946 It is implied by the \fB\-\-no\-null\fR option.
949 Instruct subsequent \fB\-T\fR options to read null-terminated names
950 verbatim (disables special handling of names that start with a dash).
952 See also \fB\-\-verbatim\-files\-from\fR.
954 \fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
955 Only store files newer than DATE. If \fIDATE\fR starts with \fB/\fR
956 or \fB.\fR it is taken to be a file name; the ctime of that file is
959 \fB\-\-one\-file\-system\fR
960 Stay in local file system when creating archive.
962 \fB\-P\fR, \fB\-\-absolute\-names\fR
963 Don't strip leading slashes from file names when creating archives.
966 Recurse into directories (default).
968 \fB\-\-suffix\fR=\fISTRING\fR
969 Backup before removal, override usual suffix. Default suffix is \fB~\fR,
970 unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
972 \fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
973 Get names to extract or create from \fIFILE\fR.
975 Unless specified otherwise, the \fIFILE\fR must contain a list of
976 names separated by ASCII \fBLF\fR (i.e. one name per line). The
977 names read are handled the same way as command line arguments. They
978 undergo quote removal and word splitting, and any string that starts
979 with a \fB\-\fR is handled as \fBtar\fR command line option.
981 If this behavior is undesirable, it can be turned off using the
982 \fB\-\-verbatim\-files\-from\fR option.
984 The \fB\-\-null\fR option instructs \fBtar\fR that the names in
985 \fIFILE\fR are separated by ASCII \fBNUL\fR character, instead of
986 \fBLF\fR. It is useful if the list is generated by
992 Unquote file or member names (default).
994 \fB\-\-verbatim\-files\-from\fR
995 Treat each line obtained from a file list as a file name, even if it
996 starts with a dash. File lists are supplied with the
997 \fB\-\-files\-from\fR (\fB\-T\fR) option. The default behavior is to
998 handle names supplied in file lists as if they were typed in the
999 command line, i.e. any names starting with a dash are treated as
1000 \fBtar\fR options. The \fB\-\-verbatim\-files\-from\fR option
1001 disables this behavior.
1003 This option affects all \fB\-\-files\-from\fR options that occur after
1004 it in the command line. Its effect is reverted by the
1005 \fB\-\-no\-verbatim\-files\-from} option.
1007 This option is implied by the \fB\-\-null\fR option.
1009 See also \fB\-\-add\-file\fR.
1011 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
1012 Exclude files matching patterns listed in FILE.
1013 .SS File name transformations
1015 \fB\-\-strip\-components\fR=\fINUMBER\fR
1016 Strip \fINUMBER\fR leading components from file names on extraction.
1018 \fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR
1019 Use sed replace \fIEXPRESSION\fR to transform file names.
1020 .SS File name matching options
1021 These options affect both exclude and include patterns.
1024 Patterns match file name start.
1026 \fB\-\-ignore\-case\fR
1029 \fB\-\-no\-anchored\fR
1030 Patterns match after any \fB/\fR (default for exclusion).
1032 \fB\-\-no\-ignore\-case\fR
1033 Case sensitive matching (default).
1035 \fB\-\-no\-wildcards\fR
1036 Verbatim string matching.
1038 \fB\-\-no\-wildcards\-match\-slash\fR
1039 Wildcards do not match \fB/\fR.
1042 Use wildcards (default for exclusion).
1044 \fB\-\-wildcards\-match\-slash\fR
1045 Wildcards match \fB/\fR (default for exclusion).
1046 .SS Informative output
1048 \fB\-\-checkpoint\fR[=\fIN\fR]
1049 Display progress messages every \fIN\fRth record (default 10).
1051 \fB\-\-checkpoint\-action\fR=\fIACTION\fR
1052 Run \fIACTION\fR on each checkpoint.
1054 \fB\-\-clamp\-mtime\fR
1055 Only set time when the file is more recent than what was given with \-\-mtime.
1057 \fB\-\-full\-time\fR
1058 Print file time to its full resolution.
1060 \fB\-\-index\-file\fR=\fIFILE\fR
1061 Send verbose output to \fIFILE\fR.
1063 \fB\-l\fR, \fB\-\-check\-links\fR
1064 Print a message if not all links are dumped.
1066 \fB\-\-no\-quote\-chars\fR=\fISTRING\fR
1067 Disable quoting for characters from \fISTRING\fR.
1069 \fB\-\-quote\-chars\fR=\fISTRING\fR
1070 Additionally quote characters from \fISTRING\fR.
1072 \fB\-\-quoting\-style\fR=\fISTYLE\fR
1073 Set quoting style for file and member names. Valid values for
1084 \fB\-R\fR, \fB\-\-block\-number\fR
1085 Show block number within archive with each message.
1087 \fB\-\-show\-omitted\-dirs\fR
1088 When listing or extracting, list each directory that does not match
1091 \fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
1092 Show file or archive names after transformation by \fB\-\-strip\fR and
1093 \fB\-\-transform\fR options.
1095 \fB\-\-totals\fR[=\fISIGNAL\fR]
1096 Print total bytes after processing the archive. If \fISIGNAL\fR is
1097 given, print total bytes when this signal is delivered. Allowed
1104 The \fBSIG\fR prefix can be omitted.
1107 Print file modification times in UTC.
1109 \fB\-v\fR, \fB\-\-verbose\fR
1110 Verbosely list files processed.
1112 \fB\-\-warning\fR=\fIKEYWORD\fR
1113 Enable or disable warning messages identified by \fIKEYWORD\fR. The
1114 messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
1115 and enabled otherwise.
1117 Multiple \fB\-\-warning\fR messages accumulate.
1119 Keywords controlling general \fBtar\fR operation:
1123 Enable all warning messages. This is the default.
1126 Disable all warning messages.
1128 .B filename-with-nuls
1129 "%s: file name read contains nul character"
1132 "A lone zero block at %s"
1134 Keywords applicable for \fBtar --create\fR:
1137 "%s: contains a cache directory tag %s; %s"
1140 "%s: File shrank by %s bytes; padding with zeros"
1143 "%s: file is on a different filesystem; not dumped"
1146 "%s: Unknown file type; file ignored"
1148 "%s: socket ignored"
1153 "%s: file is unchanged; not dumped"
1156 "%s: file is the archive; not dumped"
1159 "%s: File removed before we read it"
1162 "%s: file changed as we read it"
1164 Keywords applicable for \fBtar --extract\fR:
1167 "%s: skipping existing file"
1170 "%s: implausibly old time stamp %s"
1172 "%s: time stamp %s is %s s in the future"
1175 "Extracting contiguous files as regular files"
1178 "Attempting extraction of symbolic links as hard links"
1181 "%s: Unknown file type '%c', extracted as normal file"
1184 "Current %s is newer or same age"
1187 "Ignoring unknown extended header keyword '%s'"
1189 .B decompress-program
1190 Controls verbose description of failures occurring when trying to run
1191 alternative decompressor programs. This warning is disabled by
1192 default (unless \fB\-\-verbose\fR is used). A common example of what
1193 you can get when using this warning is:
1196 $ \fBtar --warning=decompress-program -x -f archive.Z
1197 tar (child): cannot run compress: No such file or directory
1198 tar (child): trying gzip
1201 This means that \fBtar\fR first tried to decompress
1202 \fBarchive.Z\fR using \fBcompress\fR, and, when that
1203 failed, switched to \fBgzip\fR.
1206 "Record size = %lu blocks"
1208 Keywords controlling incremental extraction:
1211 "%s: Directory has been renamed from %s"
1213 "%s: Directory has been renamed"
1216 "%s: Directory is new"
1219 "%s: directory is on a different device: not purging"
1222 "Malformed dumpdir: 'X' never used"
1225 \fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
1226 Ask for confirmation for every action.
1227 .SS Compatibility options
1230 When creating, same as \fB\-\-old\-archive\fR. When extracting, same
1231 as \fB\-\-no\-same\-owner\fR.
1237 Suffix Units Byte Equivalent
1238 b Blocks \fISIZE\fR x 512
1239 B Kilobytes \fISIZE\fR x 1024
1241 G Gigabytes \fISIZE\fR x 1024^3
1242 K Kilobytes \fISIZE\fR x 1024
1243 k Kilobytes \fISIZE\fR x 1024
1244 M Megabytes \fISIZE\fR x 1024^2
1245 P Petabytes \fISIZE\fR x 1024^5
1246 T Terabytes \fISIZE\fR x 1024^4
1247 w Words \fISIZE\fR x 2
1251 Tar exit code indicates whether it was able to successfully perform
1252 the requested operation, and if not, what kind of error occurred.
1255 Successful termination.
1258 .I Some files differ.
1259 If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
1260 command line option, this means that some files in the archive differ
1261 from their disk counterparts. If tar was given one of the \fB\-\-create\fR,
1262 \fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
1263 that some files were changed while being archived and so the resulting
1264 archive does not contain the exact copy of the file set.
1268 This means that some fatal, unrecoverable error occurred.
1270 If a subprocess that had been invoked by
1272 exited with a nonzero exit code,
1274 itself exits with that code as well. This can happen, for example, if
1275 a compression option (e.g. \fB\-z\fR) was used and the external
1276 compressor program failed. Another example is
1278 failure during backup to a remote device.
1290 Complete \fBtar\fR manual: run
1294 info mode to read it.
1296 Online copies of \fBGNU tar\fR documentation in various formats can be
1300 .B http://www.gnu.org/software/tar/manual
1302 Report bugs to <bug\-tar@gnu.org>.
1304 Copyright \(co 2013 Free Software Foundation, Inc.
1307 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
1310 This is free software: you are free to change and redistribute it.
1311 There is NO WARRANTY, to the extent permitted by law.
1312 .\" Local variables:
1313 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
1314 .\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
1315 .\" time-stamp-format: "%:B %:d, %:y"
1316 .\" time-stamp-end: "\""
1317 .\" time-stamp-line-limit: 20