1 .\" This file is part of GNU tar. -*- nroff -*-
2 .\" Copyright 2013-2023 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 "July 11, 2022" "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] \fB\-f\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\-r\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
33 \fBtar\fR \fB\-t\fR [\fB\-f\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\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] \fB\-\-file\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\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...]
50 \fBtar\fR \fB\-\-list\fR [\fB\-\-file\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\-\-extract\fR|\fB\-\-get\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...]
58 This manpage is a short description of GNU \fBtar\fR. For a detailed
59 discussion, including examples and usage recommendations, refer to the
60 \fBGNU Tar Manual\fR available in texinfo format. If the \fBinfo\fR
61 reader and the tar documentation are properly installed on your
68 should give you access to the complete manual.
70 You can also view the manual using the info mode in
72 or find it in various formats online at
75 .B http://www.gnu.org/software/tar/manual
78 If any discrepancies occur between this manpage and the
79 \fBGNU Tar Manual\fR, the later shall be considered the authoritative
84 is an archiving program designed to store multiple files in a single
85 file (an \fBarchive\fR), and to manipulate such archives. The archive
86 can be either a regular file or a device (e.g. a tape drive, hence the name
87 of the program, which stands for \fBt\fRape \fBar\fRchiver), which can
88 be located either on the local or on a remote machine.
92 Options to GNU \fBtar\fR can be given in three different styles.
94 .BR "traditional style" ,
95 the first argument is a cluster of option letters and all subsequent
96 arguments supply arguments to those options that require them. The
97 arguments are read in the same order as the option letters. Any
98 command line words that remain after all options has been processed
99 are treated as non-optional arguments: file or archive member names.
101 For example, the \fBc\fR option requires creating the archive, the
102 \fBv\fR option requests the verbose operation, and the \fBf\fR option
103 takes an argument that sets the name of the archive to operate upon.
104 The following command, written in the traditional style, instructs tar
105 to store all files from the directory
107 into the archive file
109 verbosely listing the files being archived:
116 .BR "UNIX " or " short-option style" ,
117 each option letter is prefixed with a single dash, as in other command
118 line utilities. If an option takes argument, the argument follows it,
119 either as a separate command line word, or immediately following the
120 option. However, if the option takes an \fBoptional\fR argument, the
121 argument must follow the option letter without any intervening
122 whitespace, as in \fB\-g/tmp/snar.db\fR.
124 Any number of options not taking arguments can be
125 clustered together after a single dash, e.g. \fB\-vkp\fR. Options
126 that take arguments (whether mandatory or optional), can appear at
127 the end of such a cluster, e.g. \fB\-vkpf a.tar\fR.
129 The example command above written in the
130 .B short-option style
134 tar -cvf etc.tar /etc
138 tar -c -v -f etc.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 tar --create --file etc.tar --verbose /etc
157 or (abbreviating some options):
159 tar --cre --file=etc.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
222 \fB\-r\fR options. Notice, that newer files don't replace their
223 old archive copies, but instead are appended to the end of archive.
224 The resulting archive can thus contain several members of the
225 same name, corresponding to various versions of the same file.
227 \fB\-x\fR, \fB\-\-extract\fR, \fB\-\-get\fR
228 Extract files from an archive. Arguments are optional. When given,
229 they specify names of the archive members to be extracted.
232 \fB\-\-show\-defaults\fR
233 Show built-in defaults for various \fBtar\fR options and exit. No
234 arguments are allowed.
236 \fB\-?\fR, \fB\-\-help
237 Display a short option summary and exit. No arguments allowed.
240 Display a list of available options and exit. No arguments allowed.
243 Print program version and copyright information and exit.
245 .SS Operation modifiers
247 \fB\-\-check\-device\fR
248 Check device numbers when creating incremental archives (default).
250 \fB\-g\fR, \fB\-\-listed\-incremental\fR=\fIFILE\fR
251 Handle new GNU-format incremental backups. \fIFILE\fR is the name of
252 a \fBsnapshot file\fR, where tar stores additional information which
253 is used to decide which files changed since the previous incremental
254 dump and, consequently, must be dumped again. If \fIFILE\fR does not
255 exist when creating an archive, it will be created and all files will
256 be added to the resulting archive (the \fBlevel 0\fR dump). To create
257 incremental archives of non-zero level \fBN\fR, create a copy of the
258 snapshot file created during the level \fBN-1\fR, and use it as
261 When listing or extracting, the actual contents of \fIFILE\fR is not
262 inspected, it is needed only due to syntactical requirements. It is
263 therefore common practice to use \fB/dev/null\fR in its place.
265 \fB\-\-hole\-detection\fR=\fIMETHOD\fR
266 Use \fIMETHOD\fR to detect holes in sparse files. This option implies
267 \fB\-\-sparse\fR. Valid values for \fIMETHOD\fR are \fBseek\fR and
268 \fBraw\fR. Default is \fBseek\fR with fallback to \fBraw\fR when not
271 \fB\-G\fR, \fB\-\-incremental\fR
272 Handle old GNU-format incremental backups.
274 \fB\-\-ignore\-failed\-read\fR
275 Do not exit with nonzero on unreadable files.
277 \fB\-\-level\fR=\fINUMBER\fR
278 Set dump level for created listed-incremental archive. Currently only
279 \fB\-\-level=0\fR is meaningful: it instructs \fBtar\fR to truncate
280 the snapshot file before dumping, thereby forcing a level 0 dump.
282 \fB\-n\fR, \fB\-\-seek\fR
283 Assume the archive is seekable. Normally \fBtar\fR determines
284 automatically whether the archive can be seeked or not. This option
285 is intended for use in cases when such recognition fails. It takes
286 effect only if the archive is open for reading (e.g. with
292 \fB\-\-no\-check\-device\fR
293 Do not check device numbers when creating incremental archives.
296 Assume the archive is not seekable.
298 \fB\-\-occurrence\fR[=\fIN\fR]
299 Process only the \fIN\fRth occurrence of each file in the
300 archive. This option is valid only when used with one of the
301 following subcommands: \fB\-\-delete\fR, \fB\-\-diff\fR,
302 \fB\-\-extract\fR or \fB\-\-list\fR and when a list of files is given
303 either on the command line or via the \fB\-T\fR option. The default
307 Disable the use of some potentially harmful options.
309 \fB\-\-sparse\-version\fR=\fIMAJOR\fR[.\fIMINOR\fR]
310 Set version of the sparse format to use (implies \fB\-\-sparse\fR).
313 Valid argument values are
317 For a detailed discussion of sparse formats, refer to the \fBGNU Tar
318 Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR". Using \fBinfo\fR
319 reader, it can be accessed running the following command:
320 .BR "info tar 'Sparse Formats'" .
322 \fB\-S\fR, \fB\-\-sparse\fR
323 Handle sparse files efficiently. Some files in the file system may
324 have segments which were actually never written (quite often these are
325 database files created by such systems as \fBDBM\fR). When given this
326 option, \fBtar\fR attempts to determine if the file is sparse prior to
327 archiving it, and if so, to reduce the resulting archive size by not
328 dumping empty parts of the file.
329 .SS Overwrite control
330 These options control \fBtar\fR actions when extracting a file over
331 an existing copy on disk.
333 \fB\-k\fR, \fB\-\-keep\-old\-files\fR
334 Don't replace existing files when extracting.
336 \fB\-\-keep\-newer\-files\fR
337 Don't replace existing files that are newer than their archive copies.
339 \fB\-\-keep\-directory\-symlink\fR
340 Don't replace existing symlinks to directories when extracting.
342 \fB\-\-no\-overwrite\-dir\fR
343 Preserve metadata of existing directories.
345 \fB\-\-one\-top\-level\fR[\fB=\fIDIR\fR]
346 Extract all files into \fIDIR\fR, or, if used without argument, into a
347 subdirectory named by the base name of the archive (minus standard
348 compression suffixes recognizable by \fB\-\-auto\-compress).
351 Overwrite existing files when extracting.
353 \fB\-\-overwrite\-dir\fR
354 Overwrite metadata of existing directories when extracting (default).
356 \fB\-\-recursive\-unlink\fR
357 Recursively remove all files in the directory prior to extracting it.
359 \fB\-\-remove\-files\fR
360 Remove files from disk after adding them to the archive.
362 \fB\-\-skip\-old\-files
363 Don't replace existing files when extracting, silently skip over them.
365 \fB\-U\fR, \fB\-\-unlink\-first\fR
366 Remove each file prior to extracting over it.
368 \fB\-W\fR, \fB\-\-verify\fR
369 Verify the archive after writing it.
370 .SS Output stream selection
372 \fB\-\-ignore\-command\-error\fR
374 Ignore subprocess exit codes.
376 \fB\-\-no\-ignore\-command\-error\fR
377 Treat non-zero exit codes of children as error (default).
379 \fB\-O\fR, \fB\-\-to\-stdout\fR
380 Extract files to standard output.
382 \fB\-\-to\-command\fR=\fICOMMAND\fR
383 Pipe extracted files to \fICOMMAND\fR. The argument is the pathname
384 of an external program, optionally with command line arguments. The
385 program will be invoked and the contents of the file being extracted
386 supplied to it on its standard input. Additional data will be
387 supplied via the following environment variables:
391 Type of the file. It is a single letter with the following meaning:
403 Currently only regular files are supported.
406 File mode, an octal number.
409 The name of the file.
412 Name of the file as stored in the archive.
415 Name of the file owner.
418 Name of the file owner group.
421 Time of last access. It is a decimal number, representing seconds
422 since the Epoch. If the archive provides times with nanosecond
423 precision, the nanoseconds are appended to the timestamp after a
427 Time of last modification.
430 Time of last status change.
436 UID of the file owner.
439 GID of the file owner.
443 Additionally, the following variables contain information about
444 \fBtar\fR operation mode and the archive being processed:
447 GNU \fBtar\fR version number.
450 The name of the archive \fBtar\fR is processing.
452 .B TAR_BLOCKING_FACTOR
453 Current blocking factor, i.e. number of 512-byte blocks in a record.
456 Ordinal number of the volume \fBtar\fR is processing (set if
457 reading a multi-volume archive).
460 Format of the archive being processed. One of:
468 A short option (with a leading dash) describing the operation \fBtar\fR is
471 .SS Handling of file attributes
473 \fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
474 Preserve access times on dumped files, either by restoring the times
475 after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
476 not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
478 \fB\-\-delay\-directory\-restore\fR
479 Delay setting modification times and permissions of extracted
480 directories until the end of extraction. Use this option when
481 extracting from an archive which has unusual member ordering.
483 \fB\-\-group\fR=\fINAME\fR[:\fIGID\fR]
484 Force \fINAME\fR as group for added files. If \fIGID\fR is not
485 supplied, \fINAME\fR can be either a user name or numeric GID. In
486 this case the missing part (GID or name) will be inferred from the
487 current host's group database.
489 When used with \fB\-\-group\-map\fR=\fIFILE\fR, affects only those
490 files whose owner group is not listed in \fIFILE\fR.
492 \fB\-\-group\-map\fR=\fIFILE\fR
493 Read group translation map from \fIFILE\fR. Empty lines are ignored.
494 Comments are introduced with \fB#\fR sign and extend to the end of line.
495 Each non-empty line in \fIFILE\fR defines translation for a single
496 group. It must consist of two fields, delimited by any amount of whitespace:
499 \fIOLDGRP\fR \fINEWGRP\fR[\fB:\fINEWGID\fR]
502 \fIOLDGRP\fR is either a valid group name or a GID prefixed with
503 \fB+\fR. Unless \fINEWGID\fR is supplied, \fINEWGRP\fR must also be
504 either a valid group name or a \fB+\fIGID\fR. Otherwise, both
505 \fINEWGRP\fR and \fINEWGID\fR need not be listed in the system group
508 As a result, each input file with owner group \fIOLDGRP\fR will be
509 stored in archive with owner group \fINEWGRP\fR and GID \fINEWGID\fR.
511 \fB\-\-mode\fR=\fICHANGES\fR
512 Force symbolic mode \fICHANGES\fR for added files.
514 \fB\-\-mtime\fR=\fIDATE-OR-FILE\fR
515 Set mtime for added files. \fIDATE-OR-FILE\fR is either a date/time
516 in almost arbitrary format, or the name of an existing file. In the
517 latter case the mtime of that file will be used.
519 \fB\-m\fR, \fB\-\-touch\fR
520 Don't extract file modified time.
522 \fB\-\-no\-delay\-directory\-restore\fR
523 Cancel the effect of the prior \fB\-\-delay\-directory\-restore\fR option.
525 \fB\-\-no\-same\-owner\fR
526 Extract files as yourself (default for ordinary users).
528 \fB\-\-no\-same\-permissions\fR
529 Apply the user's umask when extracting permissions from the archive
530 (default for ordinary users).
532 \fB\-\-numeric\-owner\fR
533 Always use numbers for user/group names.
535 \fB\-\-owner\fR=\fINAME\fR[:\fIUID\fR]
536 Force \fINAME\fR as owner for added files. If \fIUID\fR is not
537 supplied, \fINAME\fR can be either a user name or numeric UID. In
538 this case the missing part (UID or name) will be inferred from the
539 current host's user database.
541 When used with \fB\-\-owner\-map\fR=\fIFILE\fR, affects only those
542 files whose owner is not listed in \fIFILE\fR.
544 \fB\-\-owner\-map\fR=\fIFILE\fR
545 Read owner translation map from \fIFILE\fR. Empty lines are ignored.
546 Comments are introduced with \fB#\fR sign and extend to the end of line.
547 Each non-empty line in \fIFILE\fR defines translation for a single
548 UID. It must consist of two fields, delimited by any amount of whitespace:
551 \fIOLDUSR\fR \fINEWUSR\fR[\fB:\fINEWUID\fR]
554 \fIOLDUSR\fR is either a valid user name or a UID prefixed with
555 \fB+\fR. Unless \fINEWUID\fR is supplied, \fINEWUSR\fR must also be
556 either a valid user name or a \fB+\fIUID\fR. Otherwise, both
557 \fINEWUSR\fR and \fINEWUID\fR need not be listed in the system user
560 As a result, each input file owned by \fIOLDUSR\fR will be
561 stored in archive with owner name \fINEWUSR\fR and UID \fINEWUID\fR.
563 \fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
564 extract information about file permissions (default for superuser)
566 \fB\-\-same\-owner\fR
567 Try extracting files with the same ownership as exists in the archive
568 (default for superuser).
570 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
571 Sort names to extract to match archive
573 \fB\-\-sort=\fIORDER\fR
574 When creating an archive, sort directory entries according to
575 \fIORDER\fR, which is one of
580 The default is \fB\-\-sort=none\fR, which stores archive members in
581 the same order as returned by the operating system.
583 Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
584 is uniform and reproducible.
586 Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
587 creating the archive and thus can considerably speed up archivation.
588 This sorting order is supported only if the underlying system provides
589 the necessary information.
590 .SS Extended file attributes
593 Enable POSIX ACLs support.
596 Disable POSIX ACLs support.
599 Enable SELinux context support.
602 Disable SELinux context support.
605 Enable extended attributes support.
608 Disable extended attributes support.
610 .BI \-\-xattrs\-exclude= PATTERN
611 Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a globbing
612 pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only
613 attributes from the user namespace.
615 .BI \-\-xattrs\-include= PATTERN
616 Specify the include pattern for xattr keys. \fIPATTERN\fR is a globbing
618 .SS Device selection and switching
620 \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
621 Use archive file or device \fIARCHIVE\fR. If this option is not
622 given, \fBtar\fR will first examine the environment variable `TAPE'.
623 If it is set, its value will be used as the archive name. Otherwise,
624 \fBtar\fR will assume the compiled-in default. The default
625 value can be inspected either using the
626 .B \-\-show\-defaults
627 option, or at the end of the \fBtar \-\-help\fR output.
629 An archive name that has a colon in it specifies a file or device on a
630 remote machine. The part before the colon is taken as the machine
631 name or IP address, and the part after it as the file or device
635 --file=remotehost:/dev/sr0
638 An optional username can be prefixed to the hostname, placing a \fB@\fR
641 By default, the remote host is accessed via the
643 command. Nowadays it is common to use
645 instead. You can do so by giving the following command line option:
648 --rsh-command=/usr/bin/ssh
651 The remote machine should have the
653 command installed. If its pathname does not match \fBtar\fR's
654 default, you can inform \fBtar\fR about the correct pathname using the
658 \fB\-\-force\-local\fR
659 Archive file is local even if it has a colon.
661 \fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
662 Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The
663 command can include arguments. When started, it will inherit \fBtar\fR's
664 environment plus the following variables:
668 GNU \fBtar\fR version number.
671 The name of the archive \fBtar\fR is processing.
673 .B TAR_BLOCKING_FACTOR
674 Current blocking factor, i.e. number of 512-byte blocks in a record.
677 Ordinal number of the volume \fBtar\fR is processing (set if
678 reading a multi-volume archive).
681 Format of the archive being processed. One of:
689 A short option (with a leading dash) describing the operation \fBtar\fR is
693 File descriptor which can be used to communicate the new volume name
699 If the info script fails, \fBtar\fR exits; otherwise, it begins writing
703 \fB\-L\fR, \fB\-\-tape\-length\fR=\fIN\fR
704 Change tape after writing \fIN\fRx1024 bytes. If \fIN\fR is followed
705 by a size suffix (see the subsection
707 below), the suffix specifies the multiplicative factor to be used
713 \fB\-M\fR, \fB\-\-multi\-volume\fR
714 Create/list/extract multi-volume archive.
716 \fB\-\-rmt\-command\fR=\fICOMMAND\fR
717 Use \fICOMMAND\fR instead of \fBrmt\fR when accessing remote
718 archives. See the description of the
722 \fB\-\-rsh\-command\fR=\fICOMMAND\fR
723 Use \fICOMMAND\fR instead of \fBrsh\fR when accessing remote
724 archives. See the description of the
728 \fB\-\-volno\-file\fR=\fIFILE\fR
729 When this option is used in conjunction with
730 .BR \-\-multi\-volume ,
732 will keep track of which volume of a multi-volume archive it is
733 working in \fIFILE\fR.
736 \fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
737 Set record size to \fIBLOCKS\fRx\fB512\fR bytes.
739 \fB\-B\fR, \fB\-\-read\-full\-records\fR
740 When listing or extracting, accept incomplete input records after
743 \fB\-i\fR, \fB\-\-ignore\-zeros\fR
744 Ignore zeroed blocks in archive. Normally two consecutive 512-blocks
745 filled with zeroes mean EOF and tar stops reading after encountering
746 them. This option instructs it to read further and is useful when
747 reading archives created with the \fB\-A\fR option.
749 \fB\-\-record\-size\fR=\fINUMBER\fR
750 Set record size. \fINUMBER\fR is the number of bytes per record. It
751 must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
752 suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
754 .BR "Size suffixes" ,
755 for a list of valid suffixes.
756 .SS Archive format selection
758 \fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
759 Create archive of the given format. Valid formats are:
763 GNU tar 1.13.x format
766 GNU format as per tar <= 1.12.
768 \fBpax\fR, \fBposix\fR
769 POSIX 1003.1-2001 (pax) format.
772 POSIX 1003.1-1988 (ustar) format.
778 \fB\-\-old\-archive\fR, \fB\-\-portability\fR
779 Same as \fB\-\-format=v7\fR.
781 \fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
782 Control pax keywords when creating \fBPAX\fR archives (\fB\-H
783 pax\fR). This option is equivalent to the \fB\-o\fR option of the
788 Same as \fB\-\-format=posix\fR.
790 \fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
791 Create archive with volume name \fITEXT\fR. If listing or extracting,
792 use \fITEXT\fR as a globbing pattern for volume name.
793 .SS Compression options
795 \fB\-a\fR, \fB\-\-auto\-compress\fR
796 Use archive suffix to determine the compression program.
798 \fB\-I\fR, \fB\-\-use\-compress\-program\fI=\fICOMMAND\fR
799 Filter data through \fICOMMAND\fR. It must accept the \fB\-d\fR
800 option, for decompression. The argument can contain command line
803 \fB\-j\fR, \fB\-\-bzip2\fR
804 Filter the archive through
807 \fB\-J\fR, \fB\-\-xz\fR
808 Filter the archive through
812 Filter the archive through
816 Filter the archive through
820 Filter the archive through
823 \fB\-\-no\-auto\-compress\fR
824 Do not use archive suffix to determine the compression program.
826 \fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
827 Filter the archive through
830 \fB\-Z\fR, \fB\-\-compress\fR, \fB\-\-uncompress\fR
831 Filter the archive through
835 Filter the archive through
837 .SS Local file selection
839 \fB\-\-add\-file\fR=\fIFILE\fR
840 Add \fIFILE\fR to the archive (useful if its name starts with a dash).
842 \fB\-\-backup\fR[=\fICONTROL\fR]
843 Backup before removal. The \fICONTROL\fR argument, if supplied,
844 controls the backup policy. Its valid values are:
851 Make numbered backups.
853 .BR nil ", " existing
854 Make numbered backups if numbered backups exist, simple backups otherwise.
856 .BR never ", " simple
857 Always make simple backups
861 If \fICONTROL\fR is not given, the value is taken from the
863 environment variable. If it is not set, \fBexisting\fR is assumed.
866 \fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
867 Change to \fIDIR\fR before performing any operations. This option is
868 order-sensitive, i.e. it affects all options that follow.
870 \fB\-\-exclude\fR=\fIPATTERN\fR
871 Exclude files matching \fIPATTERN\fR, a
875 \fB\-\-exclude\-backups\fR
876 Exclude backup and lock files.
878 \fB\-\-exclude\-caches\fR
879 Exclude contents of directories containing file \fBCACHEDIR.TAG\fR,
880 except for the tag file itself.
882 \fB\-\-exclude\-caches\-all\fR
883 Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
885 \fB\-\-exclude\-caches\-under\fR
886 Exclude everything under directories containing \fBCACHEDIR.TAG\fR
888 \fB\-\-exclude\-ignore=\fIFILE\fR
889 Before dumping a directory, see if it contains \fIFILE\fR.
890 If so, read exclusion patterns from this file. The patterns affect
891 only the directory itself.
893 \fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
894 Same as \fB\-\-exclude\-ignore\fR, except that patterns from
895 \fIFILE\fR affect both the directory and all its subdirectories.
897 \fB\-\-exclude\-tag\fR=\fIFILE\fR
898 Exclude contents of directories containing \fIFILE\fR, except for
901 \fB\-\-exclude\-tag\-all\fR=\fIFILE\fR
902 Exclude directories containing \fIFILE\fR.
904 \fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
905 Exclude everything under directories containing \fIFILE\fR.
907 \fB\-\-exclude\-vcs\fR
908 Exclude version control system directories.
910 \fB\-\-exclude\-vcs\-ignores\fR
911 Exclude files that match patterns read from VCS-specific ignore
912 files. Supported files are:
915 .BR .bzrignore ", and"
918 \fB\-h\fR, \fB\-\-dereference\fR
919 Follow symlinks; archive and dump the files they point to.
921 \fB\-\-hard\-dereference\fR
922 Follow hard links; archive and dump the files they refer to.
924 \fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\fR
925 Begin at the given member in the archive.
927 \fB\-\-newer\-mtime\fR=\fIDATE\fR
928 Work on files whose data changed after the \fIDATE\fR. If \fIDATE\fR
929 starts with \fB/\fR or \fB.\fR it is taken to be a file name; the
930 mtime of that file is used as the date.
933 Disable the effect of the previous \fB\-\-null\fR option.
935 \fB\-\-no\-recursion\fR
936 Avoid descending automatically in directories.
938 \fB\-\-no\-unquote\fR
939 Do not unquote input file or member names.
941 \fB\-\-no\-verbatim\-files\-from\fR
942 Treat each line read from a file list as if it were supplied in the
943 command line. I.e., leading and trailing whitespace is removed and,
944 if the resulting string begins with a dash, it is treated as \fBtar\fR
947 This is the default behavior. The \fB\-\-no\-verbatim\-files\-from\fR
948 option is provided as a way to restore it after
949 \fB\-\-verbatim\-files\-from\fR option.
951 This option is positional: it affects all \fB\-\-files\-from\fR
952 options that occur after it in, until \fB\-\-verbatim\-files\-from\fR
953 option or end of line, whichever occurs first.
955 It is implied by the \fB\-\-no\-null\fR option.
958 Instruct subsequent \fB\-T\fR options to read null-terminated names
959 verbatim (disables special handling of names that start with a dash).
961 See also \fB\-\-verbatim\-files\-from\fR.
963 \fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
964 Only store files newer than DATE. If \fIDATE\fR starts with \fB/\fR
965 or \fB.\fR it is taken to be a file name; the mtime of that file is
968 \fB\-\-one\-file\-system\fR
969 Stay in local file system when creating archive.
971 \fB\-P\fR, \fB\-\-absolute\-names\fR
972 Don't strip leading slashes from file names when creating archives.
975 Recurse into directories (default).
977 \fB\-\-suffix\fR=\fISTRING\fR
978 Backup before removal, override usual suffix. Default suffix is \fB~\fR,
979 unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
981 \fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
982 Get names to extract or create from \fIFILE\fR.
984 Unless specified otherwise, the \fIFILE\fR must contain a list of
985 names separated by ASCII \fBLF\fR (i.e. one name per line). The
986 names read are handled the same way as command line arguments. They
987 undergo quote removal and word splitting, and any string that starts
988 with a \fB\-\fR is handled as \fBtar\fR command line option.
990 If this behavior is undesirable, it can be turned off using the
991 \fB\-\-verbatim\-files\-from\fR option.
993 The \fB\-\-null\fR option instructs \fBtar\fR that the names in
994 \fIFILE\fR are separated by ASCII \fBNUL\fR character, instead of
995 \fBLF\fR. It is useful if the list is generated by
1001 Unquote file or member names (default).
1003 \fB\-\-verbatim\-files\-from\fR
1004 Treat each line obtained from a file list as a file name, even if it
1005 starts with a dash. File lists are supplied with the
1006 \fB\-\-files\-from\fR (\fB\-T\fR) option. The default behavior is to
1007 handle names supplied in file lists as if they were typed in the
1008 command line, i.e. any names starting with a dash are treated as
1009 \fBtar\fR options. The \fB\-\-verbatim\-files\-from\fR option
1010 disables this behavior.
1012 This option affects all \fB\-\-files\-from\fR options that occur after
1013 it in the command line. Its effect is reverted by the
1014 \fB\-\-no\-verbatim\-files\-from} option.
1016 This option is implied by the \fB\-\-null\fR option.
1018 See also \fB\-\-add\-file\fR.
1020 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
1021 Exclude files matching patterns listed in FILE.
1022 .SS File name transformations
1024 \fB\-\-strip\-components\fR=\fINUMBER\fR
1025 Strip \fINUMBER\fR leading components from file names on extraction.
1027 \fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR
1028 Use sed replace \fIEXPRESSION\fR to transform file names.
1029 .SS File name matching options
1030 These options affect both exclude and include patterns.
1033 Patterns match file name start.
1035 \fB\-\-ignore\-case\fR
1038 \fB\-\-no\-anchored\fR
1039 Patterns match after any \fB/\fR (default for exclusion).
1041 \fB\-\-no\-ignore\-case\fR
1042 Case sensitive matching (default).
1044 \fB\-\-no\-wildcards\fR
1045 Verbatim string matching.
1047 \fB\-\-no\-wildcards\-match\-slash\fR
1048 Wildcards do not match \fB/\fR.
1051 Use wildcards (default for exclusion).
1053 \fB\-\-wildcards\-match\-slash\fR
1054 Wildcards match \fB/\fR (default for exclusion).
1055 .SS Informative output
1057 \fB\-\-checkpoint\fR[=\fIN\fR]
1058 Display progress messages every \fIN\fRth record (default 10).
1060 \fB\-\-checkpoint\-action\fR=\fIACTION\fR
1061 Run \fIACTION\fR on each checkpoint.
1063 \fB\-\-clamp\-mtime\fR
1064 Only set time when the file is more recent than what was given with \-\-mtime.
1066 \fB\-\-full\-time\fR
1067 Print file time to its full resolution.
1069 \fB\-\-index\-file\fR=\fIFILE\fR
1070 Send verbose output to \fIFILE\fR.
1072 \fB\-l\fR, \fB\-\-check\-links\fR
1073 Print a message if not all links are dumped.
1075 \fB\-\-no\-quote\-chars\fR=\fISTRING\fR
1076 Disable quoting for characters from \fISTRING\fR.
1078 \fB\-\-quote\-chars\fR=\fISTRING\fR
1079 Additionally quote characters from \fISTRING\fR.
1081 \fB\-\-quoting\-style\fR=\fISTYLE\fR
1082 Set quoting style for file and member names. Valid values for
1093 \fB\-R\fR, \fB\-\-block\-number\fR
1094 Show block number within archive with each message.
1096 \fB\-\-show\-omitted\-dirs\fR
1097 When listing or extracting, list each directory that does not match
1100 \fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
1101 Show file or archive names after transformation by \fB\-\-strip\fR and
1102 \fB\-\-transform\fR options.
1104 \fB\-\-totals\fR[=\fISIGNAL\fR]
1105 Print total bytes after processing the archive. If \fISIGNAL\fR is
1106 given, print total bytes when this signal is delivered. Allowed
1113 The \fBSIG\fR prefix can be omitted.
1116 Print file modification times in UTC.
1118 \fB\-v\fR, \fB\-\-verbose\fR
1119 Verbosely list files processed. Each instance of this option on the
1120 command line increases the verbosity level by one. The maximum
1121 verbosity level is 3. For a detailed discussion of how various
1122 verbosity levels affect tar's output, please refer to \fBGNU Tar
1123 Manual\fR, subsection 2.5.1 "\fBThe \-\-verbose Option\fR".
1125 \fB\-\-warning\fR=\fIKEYWORD\fR
1126 Enable or disable warning messages identified by \fIKEYWORD\fR. The
1127 messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
1128 and enabled otherwise.
1130 Multiple \fB\-\-warning\fR messages accumulate.
1132 Keywords controlling general \fBtar\fR operation:
1136 Enable all warning messages. This is the default.
1139 Disable all warning messages.
1141 .B filename-with-nuls
1142 "%s: file name read contains nul character"
1145 "A lone zero block at %s"
1147 Keywords applicable for \fBtar --create\fR:
1150 "%s: contains a cache directory tag %s; %s"
1153 "%s: File shrank by %s bytes; padding with zeros"
1156 "%s: file is on a different filesystem; not dumped"
1159 "%s: Unknown file type; file ignored"
1161 "%s: socket ignored"
1166 "%s: file is unchanged; not dumped"
1169 "%s: archive cannot contain itself; not dumped"
1172 "%s: File removed before we read it"
1175 "%s: file changed as we read it"
1178 Suppresses warnings about unreadable files or directories. This
1179 keyword applies only if used together with the
1180 .B \-\-ignore\-failed\-read
1183 Keywords applicable for \fBtar --extract\fR:
1186 "%s: skipping existing file"
1189 "%s: implausibly old time stamp %s"
1191 "%s: time stamp %s is %s s in the future"
1194 "Extracting contiguous files as regular files"
1197 "Attempting extraction of symbolic links as hard links"
1200 "%s: Unknown file type '%c', extracted as normal file"
1203 "Current %s is newer or same age"
1206 "Ignoring unknown extended header keyword '%s'"
1208 .B decompress-program
1209 Controls verbose description of failures occurring when trying to run
1210 alternative decompressor programs. This warning is disabled by
1211 default (unless \fB\-\-verbose\fR is used). A common example of what
1212 you can get when using this warning is:
1215 $ tar --warning=decompress-program -x -f archive.Z
1216 tar (child): cannot run compress: No such file or directory
1217 tar (child): trying gzip
1220 This means that \fBtar\fR first tried to decompress
1221 \fBarchive.Z\fR using \fBcompress\fR, and, when that
1222 failed, switched to \fBgzip\fR.
1225 "Record size = %lu blocks"
1227 Keywords controlling incremental extraction:
1230 "%s: Directory has been renamed from %s"
1232 "%s: Directory has been renamed"
1235 "%s: Directory is new"
1238 "%s: directory is on a different device: not purging"
1241 "Malformed dumpdir: 'X' never used"
1244 \fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
1245 Ask for confirmation for every action.
1246 .SS Compatibility options
1249 When creating, same as \fB\-\-old\-archive\fR. When extracting, same
1250 as \fB\-\-no\-same\-owner\fR.
1256 Suffix Units Byte Equivalent
1257 b Blocks \fISIZE\fR x 512
1258 B Kilobytes \fISIZE\fR x 1024
1260 G Gigabytes \fISIZE\fR x 1024^3
1261 K Kilobytes \fISIZE\fR x 1024
1262 k Kilobytes \fISIZE\fR x 1024
1263 M Megabytes \fISIZE\fR x 1024^2
1264 P Petabytes \fISIZE\fR x 1024^5
1265 T Terabytes \fISIZE\fR x 1024^4
1266 w Words \fISIZE\fR x 2
1270 Tar exit code indicates whether it was able to successfully perform
1271 the requested operation, and if not, what kind of error occurred.
1274 Successful termination.
1277 .I Some files differ.
1278 If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
1279 command line option, this means that some files in the archive differ
1280 from their disk counterparts. If tar was given one of the \fB\-\-create\fR,
1281 \fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
1282 that some files were changed while being archived and so the resulting
1283 archive does not contain the exact copy of the file set.
1287 This means that some fatal, unrecoverable error occurred.
1289 If a subprocess that had been invoked by
1291 exited with a nonzero exit code,
1293 itself exits with that code as well. This can happen, for example, if
1294 a compression option (e.g. \fB\-z\fR) was used and the external
1295 compressor program failed. Another example is
1297 failure during backup to a remote device.
1309 Complete \fBtar\fR manual: run
1313 info mode to read it.
1315 Online copies of \fBGNU tar\fR documentation in various formats can be
1319 .B http://www.gnu.org/software/tar/manual
1321 Report bugs to <bug\-tar@gnu.org>.
1323 Copyright \(co 2013-2019 Free Software Foundation, Inc.
1326 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
1329 This is free software: you are free to change and redistribute it.
1330 There is NO WARRANTY, to the extent permitted by law.
1331 .\" Local variables:
1332 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
1333 .\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
1334 .\" time-stamp-format: "%:B %:d, %:y"
1335 .\" time-stamp-end: "\""
1336 .\" time-stamp-line-limit: 20