1 .\" This file is part of GNU tar. -*- nroff -*-
2 .\" Copyright 2013-2022 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 13, 2020" "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:
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 tar -cvf etc.tar /etc
140 tar -c -v -f etc.tar /etc
144 .BR "GNU " or " long-option style" ,
145 each option begins with two dashes and has a meaningful name,
146 consisting of lower-case letters and dashes. When used, the long
147 option can be abbreviated to its initial letters, provided that
148 this does not create ambiguity. Arguments to long options are
149 supplied either as a separate command line word, immediately following
150 the option, or separated from the option by an equals sign with no
151 intervening whitespace. Optional arguments must always use the latter
154 Here are several ways of writing the example command in this style:
157 tar --create --file etc.tar --verbose /etc
159 or (abbreviating some options):
161 tar --cre --file=etc.tar --verb /etc
164 The options in all three styles can be intermixed, although doing so
165 with old options is not encouraged.
167 The options listed in the table below tell GNU \fBtar\fR what
168 operation it is to perform. Exactly one of them must be given.
169 Meaning of non-optional arguments depends on the operation mode
172 \fB\-A\fR, \fB\-\-catenate\fR, \fB\-\-concatenate\fR
173 Append archive to the end of another archive. The arguments are
174 treated as the names of archives to append. All archives must be of
175 the same format as the archive they are appended to, otherwise the
176 resulting archive might be unusable with non-GNU implementations of
177 \fBtar\fR. Notice also that when more than one archive is given, the
178 members from archives other than the first one will be accessible in
179 the resulting archive only if using the \fB\-i\fR
180 (\fB\-\-ignore\-zeros\fR) option.
182 Compressed archives cannot be concatenated.
184 \fB\-c\fR, \fB\-\-create\fR
185 Create a new archive. Arguments supply the names of the files to be
186 archived. Directories are archived recursively, unless the
187 \fB\-\-no\-recursion\fR option is given.
189 \fB\-d\fR, \fB\-\-diff\fR, \fB\-\-compare\fR
190 Find differences between archive and file system. The arguments are
191 optional and specify archive members to compare. If not given, the
192 current working directory is assumed.
195 Delete from the archive. The arguments supply names of the archive
196 members to be removed. At least one argument must be given.
198 This option does not operate on compressed archives. There is no
199 short option equivalent.
201 \fB\-r\fR, \fB\-\-append\fR
202 Append files to the end of an archive. Arguments have the same
203 meaning as for \fB\-c\fR (\fB\-\-create\fR).
205 \fB\-t\fR, \fB\-\-list\fR
206 List the contents of an archive. Arguments are optional. When given,
207 they specify the names of the members to list.
210 Test the archive volume label and exit. When used without arguments,
211 it prints the volume label (if any) and exits with status \fB0\fR.
212 When one or more command line arguments are given.
214 compares the volume label with each argument. It exits with code
215 \fB0\fR if a match is found, and with code \fB1\fR otherwise. No
216 output is displayed, unless used together with the \fB\-v\fR
217 (\fB\-\-verbose\fR) option.
219 There is no short option equivalent for this option.
221 \fB\-u\fR, \fB\-\-update\fR
222 Append files which are newer than the corresponding copy in the
223 archive. Arguments have the same meaning as with \fB\-c\fR and
224 \fB\-r\fR options. Notice, that newer files don't replace their
225 old archive copies, but instead are appended to the end of archive.
226 The resulting archive can thus contain several members of the
227 same name, corresponding to various versions of the same file.
229 \fB\-x\fR, \fB\-\-extract\fR, \fB\-\-get\fR
230 Extract files from an archive. Arguments are optional. When given,
231 they specify names of the archive members to be extracted.
234 \fB\-\-show\-defaults\fR
235 Show built-in defaults for various \fBtar\fR options and exit. No
236 arguments are allowed.
238 \fB\-?\fR, \fB\-\-help
239 Display a short option summary and exit. No arguments allowed.
242 Display a list of available options and exit. No arguments allowed.
245 Print program version and copyright information and exit.
247 .SS Operation modifiers
249 \fB\-\-check\-device\fR
250 Check device numbers when creating incremental archives (default).
252 \fB\-g\fR, \fB\-\-listed\-incremental\fR=\fIFILE\fR
253 Handle new GNU-format incremental backups. \fIFILE\fR is the name of
254 a \fBsnapshot file\fR, where tar stores additional information which
255 is used to decide which files changed since the previous incremental
256 dump and, consequently, must be dumped again. If \fIFILE\fR does not
257 exist when creating an archive, it will be created and all files will
258 be added to the resulting archive (the \fBlevel 0\fR dump). To create
259 incremental archives of non-zero level \fBN\fR, create a copy of the
260 snapshot file created during the level \fBN-1\fR, and use it as
263 When listing or extracting, the actual contents of \fIFILE\fR is not
264 inspected, it is needed only due to syntactical requirements. It is
265 therefore common practice to use \fB/dev/null\fR in its place.
267 \fB\-\-hole\-detection\fR=\fIMETHOD\fR
268 Use \fIMETHOD\fR to detect holes in sparse files. This option implies
269 \fB\-\-sparse\fR. Valid values for \fIMETHOD\fR are \fBseek\fR and
270 \fBraw\fR. Default is \fBseek\fR with fallback to \fBraw\fR when not
273 \fB\-G\fR, \fB\-\-incremental\fR
274 Handle old GNU-format incremental backups.
276 \fB\-\-ignore\-failed\-read\fR
277 Do not exit with nonzero on unreadable files.
279 \fB\-\-level\fR=\fINUMBER\fR
280 Set dump level for created listed-incremental archive. Currently only
281 \fB\-\-level=0\fR is meaningful: it instructs \fBtar\fR to truncate
282 the snapshot file before dumping, thereby forcing a level 0 dump.
284 \fB\-n\fR, \fB\-\-seek\fR
285 Assume the archive is seekable. Normally \fBtar\fR determines
286 automatically whether the archive can be seeked or not. This option
287 is intended for use in cases when such recognition fails. It takes
288 effect only if the archive is open for reading (e.g. with
294 \fB\-\-no\-check\-device\fR
295 Do not check device numbers when creating incremental archives.
298 Assume the archive is not seekable.
300 \fB\-\-occurrence\fR[=\fIN\fR]
301 Process only the \fIN\fRth occurrence of each file in the
302 archive. This option is valid only when used with one of the
303 following subcommands: \fB\-\-delete\fR, \fB\-\-diff\fR,
304 \fB\-\-extract\fR or \fB\-\-list\fR and when a list of files is given
305 either on the command line or via the \fB\-T\fR option. The default
309 Disable the use of some potentially harmful options.
311 \fB\-\-sparse\-version\fR=\fIMAJOR\fR[.\fIMINOR\fR]
312 Set version of the sparse format to use (implies \fB\-\-sparse\fR).
315 Valid argument values are
319 For a detailed discussion of sparse formats, refer to the \fBGNU Tar
320 Manual\fR, appendix \fBD\fR, "\fBSparse Formats\fR". Using \fBinfo\fR
321 reader, it can be accessed running the following command:
322 .BR "info tar 'Sparse Formats'" .
324 \fB\-S\fR, \fB\-\-sparse\fR
325 Handle sparse files efficiently. Some files in the file system may
326 have segments which were actually never written (quite often these are
327 database files created by such systems as \fBDBM\fR). When given this
328 option, \fBtar\fR attempts to determine if the file is sparse prior to
329 archiving it, and if so, to reduce the resulting archive size by not
330 dumping empty parts of the file.
331 .SS Overwrite control
332 These options control \fBtar\fR actions when extracting a file over
333 an existing copy on disk.
335 \fB\-k\fR, \fB\-\-keep\-old\-files\fR
336 Don't replace existing files when extracting.
338 \fB\-\-keep\-newer\-files\fR
339 Don't replace existing files that are newer than their archive copies.
341 \fB\-\-keep\-directory\-symlink\fR
342 Don't replace existing symlinks to directories when extracting.
344 \fB\-\-no\-overwrite\-dir\fR
345 Preserve metadata of existing directories.
347 \fB\-\-one\-top\-level\fR[\fB=\fIDIR\fR]
348 Extract all files into \fIDIR\fR, or, if used without argument, into a
349 subdirectory named by the base name of the archive (minus standard
350 compression suffixes recognizable by \fB\-\-auto\-compress).
353 Overwrite existing files when extracting.
355 \fB\-\-overwrite\-dir\fR
356 Overwrite metadata of existing directories when extracting (default).
358 \fB\-\-recursive\-unlink\fR
359 Recursively remove all files in the directory prior to extracting it.
361 \fB\-\-remove\-files\fR
362 Remove files from disk after adding them to the archive.
364 \fB\-\-skip\-old\-files
365 Don't replace existing files when extracting, silently skip over them.
367 \fB\-U\fR, \fB\-\-unlink\-first\fR
368 Remove each file prior to extracting over it.
370 \fB\-W\fR, \fB\-\-verify\fR
371 Verify the archive after writing it.
372 .SS Output stream selection
374 \fB\-\-ignore\-command\-error\fR
376 Ignore subprocess exit codes.
378 \fB\-\-no\-ignore\-command\-error\fR
379 Treat non-zero exit codes of children as error (default).
381 \fB\-O\fR, \fB\-\-to\-stdout\fR
382 Extract files to standard output.
384 \fB\-\-to\-command\fR=\fICOMMAND\fR
385 Pipe extracted files to \fICOMMAND\fR. The argument is the pathname
386 of an external program, optionally with command line arguments. The
387 program will be invoked and the contents of the file being extracted
388 supplied to it on its standard input. Additional data will be
389 supplied via the following environment variables:
393 Type of the file. It is a single letter with the following meaning:
405 Currently only regular files are supported.
408 File mode, an octal number.
411 The name of the file.
414 Name of the file as stored in the archive.
417 Name of the file owner.
420 Name of the file owner group.
423 Time of last access. It is a decimal number, representing seconds
424 since the Epoch. If the archive provides times with nanosecond
425 precision, the nanoseconds are appended to the timestamp after a
429 Time of last modification.
432 Time of last status change.
438 UID of the file owner.
441 GID of the file owner.
445 Additionally, the following variables contain information about
446 \fBtar\fR operation mode and the archive being processed:
449 GNU \fBtar\fR version number.
452 The name of the archive \fBtar\fR is processing.
454 .B TAR_BLOCKING_FACTOR
455 Current blocking factor, i.e. number of 512-byte blocks in a record.
458 Ordinal number of the volume \fBtar\fR is processing (set if
459 reading a multi-volume archive).
462 Format of the archive being processed. One of:
470 A short option (with a leading dash) describing the operation \fBtar\fR is
473 .SS Handling of file attributes
475 \fB\-\-atime\-preserve\fR[=\fIMETHOD\fR]
476 Preserve access times on dumped files, either by restoring the times
477 after reading (\fIMETHOD\fR=\fBreplace\fR, this is the default) or by
478 not setting the times in the first place (\fIMETHOD\fR=\fBsystem\fR)
480 \fB\-\-delay\-directory\-restore\fR
481 Delay setting modification times and permissions of extracted
482 directories until the end of extraction. Use this option when
483 extracting from an archive which has unusual member ordering.
485 \fB\-\-group\fR=\fINAME\fR[:\fIGID\fR]
486 Force \fINAME\fR as group for added files. If \fIGID\fR is not
487 supplied, \fINAME\fR can be either a user name or numeric GID. In
488 this case the missing part (GID or name) will be inferred from the
489 current host's group database.
491 When used with \fB\-\-group\-map\fR=\fIFILE\fR, affects only those
492 files whose owner group is not listed in \fIFILE\fR.
494 \fB\-\-group\-map\fR=\fIFILE\fR
495 Read group translation map from \fIFILE\fR. Empty lines are ignored.
496 Comments are introduced with \fB#\fR sign and extend to the end of line.
497 Each non-empty line in \fIFILE\fR defines translation for a single
498 group. It must consist of two fields, delimited by any amount of whitespace:
501 \fIOLDGRP\fR \fINEWGRP\fR[\fB:\fINEWGID\fR]
504 \fIOLDGRP\fR is either a valid group name or a GID prefixed with
505 \fB+\fR. Unless \fINEWGID\fR is supplied, \fINEWGRP\fR must also be
506 either a valid group name or a \fB+\fIGID\fR. Otherwise, both
507 \fINEWGRP\fR and \fINEWGID\fR need not be listed in the system group
510 As a result, each input file with owner group \fIOLDGRP\fR will be
511 stored in archive with owner group \fINEWGRP\fR and GID \fINEWGID\fR.
513 \fB\-\-mode\fR=\fICHANGES\fR
514 Force symbolic mode \fICHANGES\fR for added files.
516 \fB\-\-mtime\fR=\fIDATE-OR-FILE\fR
517 Set mtime for added files. \fIDATE-OR-FILE\fR is either a date/time
518 in almost arbitrary format, or the name of an existing file. In the
519 latter case the mtime of that file will be used.
521 \fB\-m\fR, \fB\-\-touch\fR
522 Don't extract file modified time.
524 \fB\-\-no\-delay\-directory\-restore\fR
525 Cancel the effect of the prior \fB\-\-delay\-directory\-restore\fR option.
527 \fB\-\-no\-same\-owner\fR
528 Extract files as yourself (default for ordinary users).
530 \fB\-\-no\-same\-permissions\fR
531 Apply the user's umask when extracting permissions from the archive
532 (default for ordinary users).
534 \fB\-\-numeric\-owner\fR
535 Always use numbers for user/group names.
537 \fB\-\-owner\fR=\fINAME\fR[:\fIUID\fR]
538 Force \fINAME\fR as owner for added files. If \fIUID\fR is not
539 supplied, \fINAME\fR can be either a user name or numeric UID. In
540 this case the missing part (UID or name) will be inferred from the
541 current host's user database.
543 When used with \fB\-\-owner\-map\fR=\fIFILE\fR, affects only those
544 files whose owner is not listed in \fIFILE\fR.
546 \fB\-\-owner\-map\fR=\fIFILE\fR
547 Read owner translation map from \fIFILE\fR. Empty lines are ignored.
548 Comments are introduced with \fB#\fR sign and extend to the end of line.
549 Each non-empty line in \fIFILE\fR defines translation for a single
550 UID. It must consist of two fields, delimited by any amount of whitespace:
553 \fIOLDUSR\fR \fINEWUSR\fR[\fB:\fINEWUID\fR]
556 \fIOLDUSR\fR is either a valid user name or a UID prefixed with
557 \fB+\fR. Unless \fINEWUID\fR is supplied, \fINEWUSR\fR must also be
558 either a valid user name or a \fB+\fIUID\fR. Otherwise, both
559 \fINEWUSR\fR and \fINEWUID\fR need not be listed in the system user
562 As a result, each input file owned by \fIOLDUSR\fR will be
563 stored in archive with owner name \fINEWUSR\fR and UID \fINEWUID\fR.
565 \fB\-p\fR, \fB\-\-preserve\-permissions\fR, \fB\-\-same\-permissions\fR
566 extract information about file permissions (default for superuser)
568 \fB\-\-same\-owner\fR
569 Try extracting files with the same ownership as exists in the archive
570 (default for superuser).
572 \fB\-s\fR, \fB\-\-preserve\-order\fR, \fB\-\-same\-order\fR
573 Sort names to extract to match archive
575 \fB\-\-sort=\fIORDER\fR
576 When creating an archive, sort directory entries according to
577 \fIORDER\fR, which is one of
582 The default is \fB\-\-sort=none\fR, which stores archive members in
583 the same order as returned by the operating system.
585 Using \fB\-\-sort=name\fR ensures the member ordering in the created archive
586 is uniform and reproducible.
588 Using \fB\-\-sort=inode\fR reduces the number of disk seeks made when
589 creating the archive and thus can considerably speed up archivation.
590 This sorting order is supported only if the underlying system provides
591 the necessary information.
592 .SS Extended file attributes
595 Enable POSIX ACLs support.
598 Disable POSIX ACLs support.
601 Enable SELinux context support.
604 Disable SELinux context support.
607 Enable extended attributes support.
610 Disable extended attributes support.
612 .BI \-\-xattrs\-exclude= PATTERN
613 Specify the exclude pattern for xattr keys. \fIPATTERN\fR is a POSIX
614 regular expression, e.g. \fB\-\-xattrs\-exclude='^user\.'\fR, to exclude
615 attributes from the user namespace.
617 .BI \-\-xattrs\-include= PATTERN
618 Specify the include pattern for xattr keys. \fIPATTERN\fR is a POSIX
620 .SS Device selection and switching
622 \fB\-f\fR, \fB\-\-file\fR=\fIARCHIVE\fR
623 Use archive file or device \fIARCHIVE\fR. If this option is not
624 given, \fBtar\fR will first examine the environment variable `TAPE'.
625 If it is set, its value will be used as the archive name. Otherwise,
626 \fBtar\fR will assume the compiled-in default. The default
627 value can be inspected either using the
628 .B \-\-show\-defaults
629 option, or at the end of the \fBtar \-\-help\fR output.
631 An archive name that has a colon in it specifies a file or device on a
632 remote machine. The part before the colon is taken as the machine
633 name or IP address, and the part after it as the file or device
637 --file=remotehost:/dev/sr0
640 An optional username can be prefixed to the hostname, placing a \fB@\fR
643 By default, the remote host is accessed via the
645 command. Nowadays it is common to use
647 instead. You can do so by giving the following command line option:
650 --rsh-command=/usr/bin/ssh
653 The remote machine should have the
655 command installed. If its pathname does not match \fBtar\fR's
656 default, you can inform \fBtar\fR about the correct pathname using the
660 \fB\-\-force\-local\fR
661 Archive file is local even if it has a colon.
663 \fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR
664 Run \fICOMMAND\fR at the end of each tape (implies \fB\-M\fR). The
665 command can include arguments. When started, it will inherit \fBtar\fR's
666 environment plus the following variables:
670 GNU \fBtar\fR version number.
673 The name of the archive \fBtar\fR is processing.
675 .B TAR_BLOCKING_FACTOR
676 Current blocking factor, i.e. number of 512-byte blocks in a record.
679 Ordinal number of the volume \fBtar\fR is processing (set if
680 reading a multi-volume archive).
683 Format of the archive being processed. One of:
691 A short option (with a leading dash) describing the operation \fBtar\fR is
695 File descriptor which can be used to communicate the new volume name
701 If the info script fails, \fBtar\fR exits; otherwise, it begins writing
705 \fB\-L\fR, \fB\-\-tape\-length\fR=\fIN\fR
706 Change tape after writing \fIN\fRx1024 bytes. If \fIN\fR is followed
707 by a size suffix (see the subsection
709 below), the suffix specifies the multiplicative factor to be used
715 \fB\-M\fR, \fB\-\-multi\-volume\fR
716 Create/list/extract multi-volume archive.
718 \fB\-\-rmt\-command\fR=\fICOMMAND\fR
719 Use \fICOMMAND\fR instead of \fBrmt\fR when accessing remote
720 archives. See the description of the
724 \fB\-\-rsh\-command\fR=\fICOMMAND\fR
725 Use \fICOMMAND\fR instead of \fBrsh\fR when accessing remote
726 archives. See the description of the
730 \fB\-\-volno\-file\fR=\fIFILE\fR
731 When this option is used in conjunction with
732 .BR \-\-multi\-volume ,
734 will keep track of which volume of a multi-volume archive it is
735 working in \fIFILE\fR.
738 \fB\-b\fR, \fB\-\-blocking\-factor\fR=\fIBLOCKS\fR
739 Set record size to \fIBLOCKS\fRx\fB512\fR bytes.
741 \fB\-B\fR, \fB\-\-read\-full\-records\fR
742 When listing or extracting, accept incomplete input records after
745 \fB\-i\fR, \fB\-\-ignore\-zeros\fR
746 Ignore zeroed blocks in archive. Normally two consecutive 512-blocks
747 filled with zeroes mean EOF and tar stops reading after encountering
748 them. This option instructs it to read further and is useful when
749 reading archives created with the \fB\-A\fR option.
751 \fB\-\-record\-size\fR=\fINUMBER\fR
752 Set record size. \fINUMBER\fR is the number of bytes per record. It
753 must be multiple of \fB512\fR. It can can be suffixed with a \fBsize
754 suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the
756 .BR "Size suffixes" ,
757 for a list of valid suffixes.
758 .SS Archive format selection
760 \fB\-H\fR, \fB\-\-format\fR=\fIFORMAT\fR
761 Create archive of the given format. Valid formats are:
765 GNU tar 1.13.x format
768 GNU format as per tar <= 1.12.
770 \fBpax\fR, \fBposix\fR
771 POSIX 1003.1-2001 (pax) format.
774 POSIX 1003.1-1988 (ustar) format.
780 \fB\-\-old\-archive\fR, \fB\-\-portability\fR
781 Same as \fB\-\-format=v7\fR.
783 \fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]...
784 Control pax keywords when creating \fBPAX\fR archives (\fB\-H
785 pax\fR). This option is equivalent to the \fB\-o\fR option of the
790 Same as \fB\-\-format=posix\fR.
792 \fB\-V\fR, \fB\-\-label\fR=\fITEXT\fR
793 Create archive with volume name \fITEXT\fR. If listing or extracting,
794 use \fITEXT\fR as a globbing pattern for volume name.
795 .SS Compression options
797 \fB\-a\fR, \fB\-\-auto\-compress\fR
798 Use archive suffix to determine the compression program.
800 \fB\-I\fR, \fB\-\-use\-compress\-program\fI=\fICOMMAND\fR
801 Filter data through \fICOMMAND\fR. It must accept the \fB\-d\fR
802 option, for decompression. The argument can contain command line
805 \fB\-j\fR, \fB\-\-bzip2\fR
806 Filter the archive through
809 \fB\-J\fR, \fB\-\-xz\fR
810 Filter the archive through
814 Filter the archive through
818 Filter the archive through
822 Filter the archive through
825 \fB\-\-no\-auto\-compress\fR
826 Do not use archive suffix to determine the compression program.
828 \fB\-z\fR, \fB\-\-gzip\fR, \fB\-\-gunzip\fR, \fB\-\-ungzip\fR
829 Filter the archive through
832 \fB\-Z\fR, \fB\-\-compress\fR, \fB\-\-uncompress\fR
833 Filter the archive through
837 Filter the archive through
839 .SS Local file selection
841 \fB\-\-add\-file\fR=\fIFILE\fR
842 Add \fIFILE\fR to the archive (useful if its name starts with a dash).
844 \fB\-\-backup\fR[=\fICONTROL\fR]
845 Backup before removal. The \fICONTROL\fR argument, if supplied,
846 controls the backup policy. Its valid values are:
853 Make numbered backups.
855 .BR nil ", " existing
856 Make numbered backups if numbered backups exist, simple backups otherwise.
858 .BR never ", " simple
859 Always make simple backups
863 If \fICONTROL\fR is not given, the value is taken from the
865 environment variable. If it is not set, \fBexisting\fR is assumed.
868 \fB\-C\fR, \fB\-\-directory\fR=\fIDIR\fR
869 Change to \fIDIR\fR before performing any operations. This option is
870 order-sensitive, i.e. it affects all options that follow.
872 \fB\-\-exclude\fR=\fIPATTERN\fR
873 Exclude files matching \fIPATTERN\fR, a
877 \fB\-\-exclude\-backups\fR
878 Exclude backup and lock files.
880 \fB\-\-exclude\-caches\fR
881 Exclude contents of directories containing file \fBCACHEDIR.TAG\fR,
882 except for the tag file itself.
884 \fB\-\-exclude\-caches\-all\fR
885 Exclude directories containing file \fBCACHEDIR.TAG\fR and the file itself.
887 \fB\-\-exclude\-caches\-under\fR
888 Exclude everything under directories containing \fBCACHEDIR.TAG\fR
890 \fB\-\-exclude\-ignore=\fIFILE\fR
891 Before dumping a directory, see if it contains \fIFILE\fR.
892 If so, read exclusion patterns from this file. The patterns affect
893 only the directory itself.
895 \fB\-\-exclude\-ignore\-recursive=\fIFILE\fR
896 Same as \fB\-\-exclude\-ignore\fR, except that patterns from
897 \fIFILE\fR affect both the directory and all its subdirectories.
899 \fB\-\-exclude\-tag\fR=\fIFILE\fR
900 Exclude contents of directories containing \fIFILE\fR, except for
903 \fB\-\-exclude\-tag\-all\fR=\fIFILE\fR
904 Exclude directories containing \fIFILE\fR.
906 \fB\-\-exclude\-tag\-under\fR=\fIFILE\fR
907 Exclude everything under directories containing \fIFILE\fR.
909 \fB\-\-exclude\-vcs\fR
910 Exclude version control system directories.
912 \fB\-\-exclude\-vcs\-ignores\fR
913 Exclude files that match patterns read from VCS-specific ignore
914 files. Supported files are:
917 .BR .bzrignore ", and"
920 \fB\-h\fR, \fB\-\-dereference\fR
921 Follow symlinks; archive and dump the files they point to.
923 \fB\-\-hard\-dereference\fR
924 Follow hard links; archive and dump the files they refer to.
926 \fB\-K\fR, \fB\-\-starting\-file\fR=\fIMEMBER\fR
927 Begin at the given member in the archive.
929 \fB\-\-newer\-mtime\fR=\fIDATE\fR
930 Work on files whose data changed after the \fIDATE\fR. If \fIDATE\fR
931 starts with \fB/\fR or \fB.\fR it is taken to be a file name; the
932 mtime of that file is used as the date.
935 Disable the effect of the previous \fB\-\-null\fR option.
937 \fB\-\-no\-recursion\fR
938 Avoid descending automatically in directories.
940 \fB\-\-no\-unquote\fR
941 Do not unquote input file or member names.
943 \fB\-\-no\-verbatim\-files\-from\fR
944 Treat each line read from a file list as if it were supplied in the
945 command line. I.e., leading and trailing whitespace is removed and,
946 if the resulting string begins with a dash, it is treated as \fBtar\fR
949 This is the default behavior. The \fB\-\-no\-verbatim\-files\-from\fR
950 option is provided as a way to restore it after
951 \fB\-\-verbatim\-files\-from\fR option.
953 This option is positional: it affects all \fB\-\-files\-from\fR
954 options that occur after it in, until \fB\-\-verbatim\-files\-from\fR
955 option or end of line, whichever occurs first.
957 It is implied by the \fB\-\-no\-null\fR option.
960 Instruct subsequent \fB\-T\fR options to read null-terminated names
961 verbatim (disables special handling of names that start with a dash).
963 See also \fB\-\-verbatim\-files\-from\fR.
965 \fB\-N\fR, \fB\-\-newer\fR=\fIDATE\fR, \fB\-\-after\-date\fR=\fIDATE\fR
966 Only store files newer than DATE. If \fIDATE\fR starts with \fB/\fR
967 or \fB.\fR it is taken to be a file name; the mtime of that file is
970 \fB\-\-one\-file\-system\fR
971 Stay in local file system when creating archive.
973 \fB\-P\fR, \fB\-\-absolute\-names\fR
974 Don't strip leading slashes from file names when creating archives.
977 Recurse into directories (default).
979 \fB\-\-suffix\fR=\fISTRING\fR
980 Backup before removal, override usual suffix. Default suffix is \fB~\fR,
981 unless overridden by environment variable \fBSIMPLE_BACKUP_SUFFIX\fR.
983 \fB\-T\fR, \fB\-\-files\-from\fR=\fIFILE\fR
984 Get names to extract or create from \fIFILE\fR.
986 Unless specified otherwise, the \fIFILE\fR must contain a list of
987 names separated by ASCII \fBLF\fR (i.e. one name per line). The
988 names read are handled the same way as command line arguments. They
989 undergo quote removal and word splitting, and any string that starts
990 with a \fB\-\fR is handled as \fBtar\fR command line option.
992 If this behavior is undesirable, it can be turned off using the
993 \fB\-\-verbatim\-files\-from\fR option.
995 The \fB\-\-null\fR option instructs \fBtar\fR that the names in
996 \fIFILE\fR are separated by ASCII \fBNUL\fR character, instead of
997 \fBLF\fR. It is useful if the list is generated by
1003 Unquote file or member names (default).
1005 \fB\-\-verbatim\-files\-from\fR
1006 Treat each line obtained from a file list as a file name, even if it
1007 starts with a dash. File lists are supplied with the
1008 \fB\-\-files\-from\fR (\fB\-T\fR) option. The default behavior is to
1009 handle names supplied in file lists as if they were typed in the
1010 command line, i.e. any names starting with a dash are treated as
1011 \fBtar\fR options. The \fB\-\-verbatim\-files\-from\fR option
1012 disables this behavior.
1014 This option affects all \fB\-\-files\-from\fR options that occur after
1015 it in the command line. Its effect is reverted by the
1016 \fB\-\-no\-verbatim\-files\-from} option.
1018 This option is implied by the \fB\-\-null\fR option.
1020 See also \fB\-\-add\-file\fR.
1022 \fB\-X\fR, \fB\-\-exclude\-from\fR=\fIFILE\fR
1023 Exclude files matching patterns listed in FILE.
1024 .SS File name transformations
1026 \fB\-\-strip\-components\fR=\fINUMBER\fR
1027 Strip \fINUMBER\fR leading components from file names on extraction.
1029 \fB\-\-transform\fR=\fIEXPRESSION\fR, \fB\-\-xform\fR=\fIEXPRESSION\fR
1030 Use sed replace \fIEXPRESSION\fR to transform file names.
1031 .SS File name matching options
1032 These options affect both exclude and include patterns.
1035 Patterns match file name start.
1037 \fB\-\-ignore\-case\fR
1040 \fB\-\-no\-anchored\fR
1041 Patterns match after any \fB/\fR (default for exclusion).
1043 \fB\-\-no\-ignore\-case\fR
1044 Case sensitive matching (default).
1046 \fB\-\-no\-wildcards\fR
1047 Verbatim string matching.
1049 \fB\-\-no\-wildcards\-match\-slash\fR
1050 Wildcards do not match \fB/\fR.
1053 Use wildcards (default for exclusion).
1055 \fB\-\-wildcards\-match\-slash\fR
1056 Wildcards match \fB/\fR (default for exclusion).
1057 .SS Informative output
1059 \fB\-\-checkpoint\fR[=\fIN\fR]
1060 Display progress messages every \fIN\fRth record (default 10).
1062 \fB\-\-checkpoint\-action\fR=\fIACTION\fR
1063 Run \fIACTION\fR on each checkpoint.
1065 \fB\-\-clamp\-mtime\fR
1066 Only set time when the file is more recent than what was given with \-\-mtime.
1068 \fB\-\-full\-time\fR
1069 Print file time to its full resolution.
1071 \fB\-\-index\-file\fR=\fIFILE\fR
1072 Send verbose output to \fIFILE\fR.
1074 \fB\-l\fR, \fB\-\-check\-links\fR
1075 Print a message if not all links are dumped.
1077 \fB\-\-no\-quote\-chars\fR=\fISTRING\fR
1078 Disable quoting for characters from \fISTRING\fR.
1080 \fB\-\-quote\-chars\fR=\fISTRING\fR
1081 Additionally quote characters from \fISTRING\fR.
1083 \fB\-\-quoting\-style\fR=\fISTYLE\fR
1084 Set quoting style for file and member names. Valid values for
1095 \fB\-R\fR, \fB\-\-block\-number\fR
1096 Show block number within archive with each message.
1098 \fB\-\-show\-omitted\-dirs\fR
1099 When listing or extracting, list each directory that does not match
1102 \fB\-\-show\-transformed\-names\fR, \fB\-\-show\-stored\-names\fR
1103 Show file or archive names after transformation by \fB\-\-strip\fR and
1104 \fB\-\-transform\fR options.
1106 \fB\-\-totals\fR[=\fISIGNAL\fR]
1107 Print total bytes after processing the archive. If \fISIGNAL\fR is
1108 given, print total bytes when this signal is delivered. Allowed
1115 The \fBSIG\fR prefix can be omitted.
1118 Print file modification times in UTC.
1120 \fB\-v\fR, \fB\-\-verbose\fR
1121 Verbosely list files processed. Each instance of this option on the
1122 command line increases the verbosity level by one. The maximum
1123 verbosity level is 3. For a detailed discussion of how various
1124 verbosity levels affect tar's output, please refer to \fBGNU Tar
1125 Manual\fR, subsection 2.5.1 "\fBThe \-\-verbose Option\fR".
1127 \fB\-\-warning\fR=\fIKEYWORD\fR
1128 Enable or disable warning messages identified by \fIKEYWORD\fR. The
1129 messages are suppressed if \fIKEYWORD\fR is prefixed with \fBno\-\fR
1130 and enabled otherwise.
1132 Multiple \fB\-\-warning\fR messages accumulate.
1134 Keywords controlling general \fBtar\fR operation:
1138 Enable all warning messages. This is the default.
1141 Disable all warning messages.
1143 .B filename-with-nuls
1144 "%s: file name read contains nul character"
1147 "A lone zero block at %s"
1149 Keywords applicable for \fBtar --create\fR:
1152 "%s: contains a cache directory tag %s; %s"
1155 "%s: File shrank by %s bytes; padding with zeros"
1158 "%s: file is on a different filesystem; not dumped"
1161 "%s: Unknown file type; file ignored"
1163 "%s: socket ignored"
1168 "%s: file is unchanged; not dumped"
1171 "%s: file is the archive; not dumped"
1174 "%s: File removed before we read it"
1177 "%s: file changed as we read it"
1180 Suppresses warnings about unreadable files or directories. This
1181 keyword applies only if used together with the
1182 .B \-\-ignore\-failed\-read
1185 Keywords applicable for \fBtar --extract\fR:
1188 "%s: skipping existing file"
1191 "%s: implausibly old time stamp %s"
1193 "%s: time stamp %s is %s s in the future"
1196 "Extracting contiguous files as regular files"
1199 "Attempting extraction of symbolic links as hard links"
1202 "%s: Unknown file type '%c', extracted as normal file"
1205 "Current %s is newer or same age"
1208 "Ignoring unknown extended header keyword '%s'"
1210 .B decompress-program
1211 Controls verbose description of failures occurring when trying to run
1212 alternative decompressor programs. This warning is disabled by
1213 default (unless \fB\-\-verbose\fR is used). A common example of what
1214 you can get when using this warning is:
1217 $ tar --warning=decompress-program -x -f archive.Z
1218 tar (child): cannot run compress: No such file or directory
1219 tar (child): trying gzip
1222 This means that \fBtar\fR first tried to decompress
1223 \fBarchive.Z\fR using \fBcompress\fR, and, when that
1224 failed, switched to \fBgzip\fR.
1227 "Record size = %lu blocks"
1229 Keywords controlling incremental extraction:
1232 "%s: Directory has been renamed from %s"
1234 "%s: Directory has been renamed"
1237 "%s: Directory is new"
1240 "%s: directory is on a different device: not purging"
1243 "Malformed dumpdir: 'X' never used"
1246 \fB\-w\fR, \fB\-\-interactive\fR, \fB\-\-confirmation\fR
1247 Ask for confirmation for every action.
1248 .SS Compatibility options
1251 When creating, same as \fB\-\-old\-archive\fR. When extracting, same
1252 as \fB\-\-no\-same\-owner\fR.
1258 Suffix Units Byte Equivalent
1259 b Blocks \fISIZE\fR x 512
1260 B Kilobytes \fISIZE\fR x 1024
1262 G Gigabytes \fISIZE\fR x 1024^3
1263 K Kilobytes \fISIZE\fR x 1024
1264 k Kilobytes \fISIZE\fR x 1024
1265 M Megabytes \fISIZE\fR x 1024^2
1266 P Petabytes \fISIZE\fR x 1024^5
1267 T Terabytes \fISIZE\fR x 1024^4
1268 w Words \fISIZE\fR x 2
1272 Tar exit code indicates whether it was able to successfully perform
1273 the requested operation, and if not, what kind of error occurred.
1276 Successful termination.
1279 .I Some files differ.
1280 If tar was invoked with the \fB\-\-compare\fR (\fB\-\-diff\fR, \fB\-d\fR)
1281 command line option, this means that some files in the archive differ
1282 from their disk counterparts. If tar was given one of the \fB\-\-create\fR,
1283 \fB\-\-append\fR or \fB\-\-update\fR options, this exit code means
1284 that some files were changed while being archived and so the resulting
1285 archive does not contain the exact copy of the file set.
1289 This means that some fatal, unrecoverable error occurred.
1291 If a subprocess that had been invoked by
1293 exited with a nonzero exit code,
1295 itself exits with that code as well. This can happen, for example, if
1296 a compression option (e.g. \fB\-z\fR) was used and the external
1297 compressor program failed. Another example is
1299 failure during backup to a remote device.
1311 Complete \fBtar\fR manual: run
1315 info mode to read it.
1317 Online copies of \fBGNU tar\fR documentation in various formats can be
1321 .B http://www.gnu.org/software/tar/manual
1323 Report bugs to <bug\-tar@gnu.org>.
1325 Copyright \(co 2013-2019 Free Software Foundation, Inc.
1328 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
1331 This is free software: you are free to change and redistribute it.
1332 There is NO WARRANTY, to the extent permitted by law.
1333 .\" Local variables:
1334 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
1335 .\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
1336 .\" time-stamp-format: "%:B %:d, %:y"
1337 .\" time-stamp-end: "\""
1338 .\" time-stamp-line-limit: 20