1TAR(1) GNU TAR Manual TAR(1)
2
6 tar - an archiving utility
7
9 Traditional usage
10 tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ARG...]
11 UNIX-style usage
13 tar -A [OPTIONS] ARCHIVE ARCHIVE
14 tar -c [-f ARCHIVE] [OPTIONS] [FILE...]
16 tar -d [-f ARCHIVE] [OPTIONS] [FILE...]
18 tar -t [-f ARCHIVE] [OPTIONS] [MEMBER...]
20 tar -r [-f ARCHIVE] [OPTIONS] [FILE...]
22 tar -u [-f ARCHIVE] [OPTIONS] [FILE...]
24 tar -x [-f ARCHIVE] [OPTIONS] [MEMBER...]
26 GNU-style usage
28 tar {--catenate|--concatenate} [OPTIONS] ARCHIVE ARCHIVE
29 tar --create [--file ARCHIVE] [OPTIONS] [FILE...]
31 tar {--diff|--compare} [--file ARCHIVE] [OPTIONS] [FILE...]
33 tar --delete [--file ARCHIVE] [OPTIONS] [MEMBER...]
35 tar --append [-f ARCHIVE] [OPTIONS] [FILE...]
37 tar --list [-f ARCHIVE] [OPTIONS] [MEMBER...]
39 tar --test-label [--file ARCHIVE] [OPTIONS] [LABEL...]
41 tar --update [--file ARCHIVE] [OPTIONS] [FILE...]
43 tar --update [-f ARCHIVE] [OPTIONS] [FILE...]
45 tar {--extract|--get} [-f ARCHIVE] [OPTIONS] [MEMBER...]
47
49 This manpage is a short description of GNU tar. For a detailed discus‐
50 sion, including examples and usage recommendations, refer to the GNU
51 Tar Manual available in texinfo format. If the info reader and the tar
52 documentation are properly installed on your system, the command
53 info tar
55 should give you access to the complete manual.
57 You can also view the manual using the info mode in emacs(1), or find
59 it in various formats online at
60 http://www.gnu.org/software/tar/manual
62 If any discrepancies occur between this manpage and the GNU Tar Manual,
64 the later shall be considered the authoritative source.
65
67 GNU tar is an archiving program designed to store multiple files in a
68 single file (an archive), and to manipulate such archives. The archive
69 can be either a regular file or a device (e.g. a tape drive, hence the
70 name of the program, which stands for tape archiver), which can be lo‐
71 cated either on the local or on a remote machine.
72 Option styles
74 Options to GNU tar can be given in three different styles. In tradi‐
75 tional style, the first argument is a cluster of option letters and all
76 subsequent arguments supply arguments to those options that require
77 them. The arguments are read in the same order as the option letters.
78 Any command line words that remain after all options has been processed
79 are treated as non-optional arguments: file or archive member names.
80 For example, the c option requires creating the archive, the v option
82 requests the verbose operation, and the f option takes an argument that
83 sets the name of the archive to operate upon. The following command,
84 written in the traditional style, instructs tar to store all files from
85 the directory /etc into the archive file etc.tar verbosely listing the
86 files being archived:
87 tar cfv etc.tar /etc
89 In UNIX or short-option style, each option letter is prefixed with a
91 single dash, as in other command line utilities. If an option takes
92 argument, the argument follows it, either as a separate command line
93 word, or immediately following the option. However, if the option
94 takes an optional argument, the argument must follow the option letter
95 without any intervening whitespace, as in -g/tmp/snar.db.
96 Any number of options not taking arguments can be clustered together
98 after a single dash, e.g. -vkp. Options that take arguments (whether
99 mandatory or optional), can appear at the end of such a cluster, e.g.
100 -vkpf a.tar.
101 The example command above written in the short-option style could look
103 like:
104 tar -cvf etc.tar /etc
106 or
107 tar -c -v -f etc.tar /etc
108 In GNU or long-option style, each option begins with two dashes and has
110 a meaningful name, consisting of lower-case letters and dashes. When
111 used, the long option can be abbreviated to its initial letters, pro‐
112 vided that this does not create ambiguity. Arguments to long options
113 are supplied either as a separate command line word, immediately fol‐
114 lowing the option, or separated from the option by an equals sign with
115 no intervening whitespace. Optional arguments must always use the lat‐
116 ter method.
117 Here are several ways of writing the example command in this style:
119 tar --create --file etc.tar --verbose /etc
121 or (abbreviating some options):
122 tar --cre --file=etc.tar --verb /etc
123 The options in all three styles can be intermixed, although doing so
125 with old options is not encouraged.
126 Operation mode
128 The options listed in the table below tell GNU tar what operation it is
129 to perform. Exactly one of them must be given. Meaning of non-op‐
130 tional arguments depends on the operation mode requested.
131 -A, --catenate, --concatenate
133 Append archive to the end of another archive. The arguments are
134 treated as the names of archives to append. All archives must
135 be of the same format as the archive they are appended to, oth‐
136 erwise the resulting archive might be unusable with non-GNU im‐
137 plementations of tar. Notice also that when more than one ar‐
138 chive is given, the members from archives other than the first
139 one will be accessible in the resulting archive only if using
140 the -i (--ignore-zeros) option.
141 Compressed archives cannot be concatenated.
143 -c, --create
145 Create a new archive. Arguments supply the names of the files
146 to be archived. Directories are archived recursively, unless
147 the --no-recursion option is given.
148 -d, --diff, --compare
150 Find differences between archive and file system. The arguments
151 are optional and specify archive members to compare. If not
152 given, the current working directory is assumed.
153 --delete
155 Delete from the archive. The arguments supply names of the ar‐
156 chive members to be removed. At least one argument must be
157 given.
158 This option does not operate on compressed archives. There is
160 no short option equivalent.
161 -r, --append
163 Append files to the end of an archive. Arguments have the same
164 meaning as for -c (--create).
165 -t, --list
167 List the contents of an archive. Arguments are optional. When
168 given, they specify the names of the members to list.
169 --test-label
171 Test the archive volume label and exit. When used without argu‐
172 ments, it prints the volume label (if any) and exits with status
173 0. When one or more command line arguments are given. tar com‐
174 pares the volume label with each argument. It exits with code 0
175 if a match is found, and with code 1 otherwise. No output is
176 displayed, unless used together with the -v (--verbose) option.
177 There is no short option equivalent for this option.
179 -u, --update
181 Append files which are newer than the corresponding copy in the
182 archive. Arguments have the same meaning as with -c and -r op‐
183 tions. Notice, that newer files don't replace their old archive
184 copies, but instead are appended to the end of archive. The re‐
185 sulting archive can thus contain several members of the same
186 name, corresponding to various versions of the same file.
187 -x, --extract, --get
189 Extract files from an archive. Arguments are optional. When
190 given, they specify names of the archive members to be ex‐
191 tracted.
192 --show-defaults
195 Show built-in defaults for various tar options and exit. No ar‐
196 guments are allowed.
197 -?, --help
199 Display a short option summary and exit. No arguments allowed.
200 --usage
202 Display a list of available options and exit. No arguments al‐
203 lowed.
204 --version
206 Print program version and copyright information and exit.
207
209 Operation modifiers
210 --check-device
211 Check device numbers when creating incremental archives (de‐
212 fault).
213 -g, --listed-incremental=FILE
215 Handle new GNU-format incremental backups. FILE is the name of
216 a snapshot file, where tar stores additional information which
217 is used to decide which files changed since the previous incre‐
218 mental dump and, consequently, must be dumped again. If FILE
219 does not exist when creating an archive, it will be created and
220 all files will be added to the resulting archive (the level 0
221 dump). To create incremental archives of non-zero level N, cre‐
222 ate a copy of the snapshot file created during the level N-1,
223 and use it as FILE.
224 When listing or extracting, the actual contents of FILE is not
226 inspected, it is needed only due to syntactical requirements.
227 It is therefore common practice to use /dev/null in its place.
228 --hole-detection=METHOD
230 Use METHOD to detect holes in sparse files. This option implies
231 --sparse. Valid values for METHOD are seek and raw. Default is
232 seek with fallback to raw when not applicable.
233 -G, --incremental
235 Handle old GNU-format incremental backups.
236 --ignore-failed-read
238 Do not exit with nonzero on unreadable files.
239 --level=NUMBER
241 Set dump level for created listed-incremental archive. Cur‐
242 rently only --level=0 is meaningful: it instructs tar to trun‐
243 cate the snapshot file before dumping, thereby forcing a level 0
244 dump.
245 -n, --seek
247 Assume the archive is seekable. Normally tar determines auto‐
248 matically whether the archive can be seeked or not. This option
249 is intended for use in cases when such recognition fails. It
250 takes effect only if the archive is open for reading (e.g. with
251 --list or --extract options).
252 --no-check-device
254 Do not check device numbers when creating incremental archives.
255 --no-seek
257 Assume the archive is not seekable.
258 --occurrence[=N]
260 Process only the Nth occurrence of each file in the archive.
261 This option is valid only when used with one of the following
262 subcommands: --delete, --diff, --extract or --list and when a
263 list of files is given either on the command line or via the -T
264 option. The default N is 1.
265 --restrict
267 Disable the use of some potentially harmful options.
268 --sparse-version=MAJOR[.MINOR]
270 Set version of the sparse format to use (implies --sparse).
271 This option implies --sparse. Valid argument values are 0.0,
272 0.1, and 1.0. For a detailed discussion of sparse formats, re‐
273 fer to the GNU Tar Manual, appendix D, "Sparse Formats". Using
274 info reader, it can be accessed running the following command:
275 info tar 'Sparse Formats'.
276 -S, --sparse
278 Handle sparse files efficiently. Some files in the file system
279 may have segments which were actually never written (quite often
280 these are database files created by such systems as DBM). When
281 given this option, tar attempts to determine if the file is
282 sparse prior to archiving it, and if so, to reduce the resulting
283 archive size by not dumping empty parts of the file.
284 Overwrite control
286 These options control tar actions when extracting a file over an exist‐
287 ing copy on disk.
288 -k, --keep-old-files
290 Don't replace existing files when extracting.
291 --keep-newer-files
293 Don't replace existing files that are newer than their archive
294 copies.
295 --keep-directory-symlink
297 Don't replace existing symlinks to directories when extracting.
298 --no-overwrite-dir
300 Preserve metadata of existing directories.
301 --one-top-level[=DIR]
303 Extract all files into DIR, or, if used without argument, into a
304 subdirectory named by the base name of the archive (minus stan‐
305 dard compression suffixes recognizable by --auto-compress).
306 --overwrite
308 Overwrite existing files when extracting.
309 --overwrite-dir
311 Overwrite metadata of existing directories when extracting (de‐
312 fault).
313 --recursive-unlink
315 Recursively remove all files in the directory prior to extract‐
316 ing it.
317 --remove-files
319 Remove files from disk after adding them to the archive.
320 --skip-old-files
322 Don't replace existing files when extracting, silently skip over
323 them.
324 -U, --unlink-first
326 Remove each file prior to extracting over it.
327 -W, --verify
329 Verify the archive after writing it.
330 Output stream selection
332 --ignore-command-error
333 Ignore subprocess exit codes.
335 --no-ignore-command-error
337 Treat non-zero exit codes of children as error (default).
338 -O, --to-stdout
340 Extract files to standard output.
341 --to-command=COMMAND
343 Pipe extracted files to COMMAND. The argument is the pathname
344 of an external program, optionally with command line arguments.
345 The program will be invoked and the contents of the file being
346 extracted supplied to it on its standard input. Additional data
347 will be supplied via the following environment variables:
348 TAR_FILETYPE
350 Type of the file. It is a single letter with the follow‐
351 ing meaning:
352 f Regular file
354 d Directory
355 l Symbolic link
356 h Hard link
357 b Block device
358 c Character device
359 Currently only regular files are supported.
361 TAR_MODE
363 File mode, an octal number.
364 TAR_FILENAME
366 The name of the file.
367 TAR_REALNAME
369 Name of the file as stored in the archive.
370 TAR_UNAME
372 Name of the file owner.
373 TAR_GNAME
375 Name of the file owner group.
376 TAR_ATIME
378 Time of last access. It is a decimal number, representing
379 seconds since the Epoch. If the archive provides times
380 with nanosecond precision, the nanoseconds are appended
381 to the timestamp after a decimal point.
382 TAR_MTIME
384 Time of last modification.
385 TAR_CTIME
387 Time of last status change.
388 TAR_SIZE
390 Size of the file.
391 TAR_UID
393 UID of the file owner.
394 TAR_GID
396 GID of the file owner.
397 Additionally, the following variables contain information about
399 tar operation mode and the archive being processed:
400 TAR_VERSION
402 GNU tar version number.
403 TAR_ARCHIVE
405 The name of the archive tar is processing.
406 TAR_BLOCKING_FACTOR
408 Current blocking factor, i.e. number of 512-byte blocks
409 in a record.
410 TAR_VOLUME
412 Ordinal number of the volume tar is processing (set if
413 reading a multi-volume archive).
414 TAR_FORMAT
416 Format of the archive being processed. One of: gnu,
417 oldgnu, posix, ustar, v7.
418 TAR_SUBCOMMAND
420 A short option (with a leading dash) describing the oper‐
421 ation tar is executing.
422 Handling of file attributes
424 --atime-preserve[=METHOD]
425 Preserve access times on dumped files, either by restoring the
426 times after reading (METHOD=replace, this is the default) or by
427 not setting the times in the first place (METHOD=system)
428 --delay-directory-restore
430 Delay setting modification times and permissions of extracted
431 directories until the end of extraction. Use this option when
432 extracting from an archive which has unusual member ordering.
433 --group=NAME[:GID]
435 Force NAME as group for added files. If GID is not supplied,
436 NAME can be either a user name or numeric GID. In this case the
437 missing part (GID or name) will be inferred from the current
438 host's group database.
439 When used with --group-map=FILE, affects only those files whose
441 owner group is not listed in FILE.
442 --group-map=FILE
444 Read group translation map from FILE. Empty lines are ignored.
445 Comments are introduced with # sign and extend to the end of
446 line. Each non-empty line in FILE defines translation for a
447 single group. It must consist of two fields, delimited by any
448 amount of whitespace:
449 OLDGRP NEWGRP[:NEWGID]
451 OLDGRP is either a valid group name or a GID prefixed with +.
453 Unless NEWGID is supplied, NEWGRP must also be either a valid
454 group name or a +GID. Otherwise, both NEWGRP and NEWGID need
455 not be listed in the system group database.
456 As a result, each input file with owner group OLDGRP will be
458 stored in archive with owner group NEWGRP and GID NEWGID.
459 --mode=CHANGES
461 Force symbolic mode CHANGES for added files.
462 --mtime=DATE-OR-FILE
464 Set mtime for added files. DATE-OR-FILE is either a date/time
465 in almost arbitrary format, or the name of an existing file. In
466 the latter case the mtime of that file will be used.
467 -m, --touch
469 Don't extract file modified time.
470 --no-delay-directory-restore
472 Cancel the effect of the prior --delay-directory-restore option.
473 --no-same-owner
475 Extract files as yourself (default for ordinary users).
476 --no-same-permissions
478 Apply the user's umask when extracting permissions from the ar‐
479 chive (default for ordinary users).
480 --numeric-owner
482 Always use numbers for user/group names.
483 --owner=NAME[:UID]
485 Force NAME as owner for added files. If UID is not supplied,
486 NAME can be either a user name or numeric UID. In this case the
487 missing part (UID or name) will be inferred from the current
488 host's user database.
489 When used with --owner-map=FILE, affects only those files whose
491 owner is not listed in FILE.
492 --owner-map=FILE
494 Read owner translation map from FILE. Empty lines are ignored.
495 Comments are introduced with # sign and extend to the end of
496 line. Each non-empty line in FILE defines translation for a
497 single UID. It must consist of two fields, delimited by any
498 amount of whitespace:
499 OLDUSR NEWUSR[:NEWUID]
501 OLDUSR is either a valid user name or a UID prefixed with +.
503 Unless NEWUID is supplied, NEWUSR must also be either a valid
504 user name or a +UID. Otherwise, both NEWUSR and NEWUID need not
505 be listed in the system user database.
506 As a result, each input file owned by OLDUSR will be stored in
508 archive with owner name NEWUSR and UID NEWUID.
509 -p, --preserve-permissions, --same-permissions
511 extract information about file permissions (default for supe‐
512 ruser)
513 --same-owner
515 Try extracting files with the same ownership as exists in the
516 archive (default for superuser).
517 -s, --preserve-order, --same-order
519 Sort names to extract to match archive
520 --sort=ORDER
522 When creating an archive, sort directory entries according to
523 ORDER, which is one of none, name, or inode.
524 The default is --sort=none, which stores archive members in the
526 same order as returned by the operating system.
527 Using --sort=name ensures the member ordering in the created ar‐
529 chive is uniform and reproducible.
530 Using --sort=inode reduces the number of disk seeks made when
532 creating the archive and thus can considerably speed up archiva‐
533 tion. This sorting order is supported only if the underlying
534 system provides the necessary information.
535 Extended file attributes
537 --acls Enable POSIX ACLs support.
538 --no-acls
540 Disable POSIX ACLs support.
541 --selinux
543 Enable SELinux context support.
544 --no-selinux
546 Disable SELinux context support.
547 --xattrs
549 Enable extended attributes support.
550 --no-xattrs
552 Disable extended attributes support.
553 --xattrs-exclude=PATTERN
555 Specify the exclude pattern for xattr keys. PATTERN is a POSIX
556 regular expression, e.g. --xattrs-exclude='^user.', to exclude
557 attributes from the user namespace.
558 --xattrs-include=PATTERN
560 Specify the include pattern for xattr keys. PATTERN is a POSIX
561 regular expression.
562 Device selection and switching
564 -f, --file=ARCHIVE
565 Use archive file or device ARCHIVE. If this option is not
566 given, tar will first examine the environment variable `TAPE'.
567 If it is set, its value will be used as the archive name. Oth‐
568 erwise, tar will assume the compiled-in default. The default
569 value can be inspected either using the --show-defaults option,
570 or at the end of the tar --help output.
571 An archive name that has a colon in it specifies a file or de‐
573 vice on a remote machine. The part before the colon is taken as
574 the machine name or IP address, and the part after it as the
575 file or device pathname, e.g.:
576 --file=remotehost:/dev/sr0
578 An optional username can be prefixed to the hostname, placing a
580 @ sign between them.
581 By default, the remote host is accessed via the rsh(1) command.
583 Nowadays it is common to use ssh(1) instead. You can do so by
584 giving the following command line option:
585 --rsh-command=/usr/bin/ssh
587 The remote machine should have the rmt(8) command installed. If
589 its pathname does not match tar's default, you can inform tar
590 about the correct pathname using the --rmt-command option.
591 --force-local
593 Archive file is local even if it has a colon.
594 -F, --info-script=COMMAND, --new-volume-script=COMMAND
596 Run COMMAND at the end of each tape (implies -M). The command
597 can include arguments. When started, it will inherit tar's en‐
598 vironment plus the following variables:
599 TAR_VERSION
601 GNU tar version number.
602 TAR_ARCHIVE
604 The name of the archive tar is processing.
605 TAR_BLOCKING_FACTOR
607 Current blocking factor, i.e. number of 512-byte blocks
608 in a record.
609 TAR_VOLUME
611 Ordinal number of the volume tar is processing (set if
612 reading a multi-volume archive).
613 TAR_FORMAT
615 Format of the archive being processed. One of: gnu,
616 oldgnu, posix, ustar, v7.
617 TAR_SUBCOMMAND
619 A short option (with a leading dash) describing the oper‐
620 ation tar is executing.
621 TAR_FD File descriptor which can be used to communicate the new
623 volume name to tar.
624 If the info script fails, tar exits; otherwise, it begins writ‐
626 ing the next volume.
627 -L, --tape-length=N
629 Change tape after writing Nx1024 bytes. If N is followed by a
630 size suffix (see the subsection Size suffixes below), the suffix
631 specifies the multiplicative factor to be used instead of 1024.
632 This option implies -M.
634 -M, --multi-volume
636 Create/list/extract multi-volume archive.
637 --rmt-command=COMMAND
639 Use COMMAND instead of rmt when accessing remote archives. See
640 the description of the -f option, above.
641 --rsh-command=COMMAND
643 Use COMMAND instead of rsh when accessing remote archives. See
644 the description of the -f option, above.
645 --volno-file=FILE
647 When this option is used in conjunction with --multi-volume, tar
648 will keep track of which volume of a multi-volume archive it is
649 working in FILE.
650 Device blocking
652 -b, --blocking-factor=BLOCKS
653 Set record size to BLOCKSx512 bytes.
654 -B, --read-full-records
656 When listing or extracting, accept incomplete input records af‐
657 ter end-of-file marker.
658 -i, --ignore-zeros
660 Ignore zeroed blocks in archive. Normally two consecutive
661 512-blocks filled with zeroes mean EOF and tar stops reading af‐
662 ter encountering them. This option instructs it to read further
663 and is useful when reading archives created with the -A option.
664 --record-size=NUMBER
666 Set record size. NUMBER is the number of bytes per record. It
667 must be multiple of 512. It can can be suffixed with a size
668 suffix, e.g. --record-size=10K, for 10 Kilobytes. See the sub‐
669 section Size suffixes, for a list of valid suffixes.
670 Archive format selection
672 -H, --format=FORMAT
673 Create archive of the given format. Valid formats are:
674 gnu GNU tar 1.13.x format
676 oldgnu GNU format as per tar <= 1.12.
678 pax, posix
680 POSIX 1003.1-2001 (pax) format.
681 ustar POSIX 1003.1-1988 (ustar) format.
683 v7 Old V7 tar format.
685 --old-archive, --portability
687 Same as --format=v7.
688 --pax-option=keyword[[:]=value][,keyword[[:]=value]]...
690 Control pax keywords when creating PAX archives (-H pax). This
691 option is equivalent to the -o option of the pax(1) utility.
692 --posix
694 Same as --format=posix.
695 -V, --label=TEXT
697 Create archive with volume name TEXT. If listing or extracting,
698 use TEXT as a globbing pattern for volume name.
699 Compression options
701 -a, --auto-compress
702 Use archive suffix to determine the compression program.
703 -I, --use-compress-program=COMMAND
705 Filter data through COMMAND. It must accept the -d option, for
706 decompression. The argument can contain command line options.
707 -j, --bzip2
709 Filter the archive through bzip2(1).
710 -J, --xz
712 Filter the archive through xz(1).
713 --lzip Filter the archive through lzip(1).
715 --lzma Filter the archive through lzma(1).
717 --lzop Filter the archive through lzop(1).
719 --no-auto-compress
721 Do not use archive suffix to determine the compression program.
722 -z, --gzip, --gunzip, --ungzip
724 Filter the archive through gzip(1).
725 -Z, --compress, --uncompress
727 Filter the archive through compress(1).
728 --zstd Filter the archive through zstd(1).
730 Local file selection
732 --add-file=FILE
733 Add FILE to the archive (useful if its name starts with a dash).
734 --backup[=CONTROL]
736 Backup before removal. The CONTROL argument, if supplied, con‐
737 trols the backup policy. Its valid values are:
738 none, off
740 Never make backups.
741 t, numbered
743 Make numbered backups.
744 nil, existing
746 Make numbered backups if numbered backups exist, simple
747 backups otherwise.
748 never, simple
750 Always make simple backups
751 If CONTROL is not given, the value is taken from the VER‐
753 SION_CONTROL environment variable. If it is not set, existing
754 is assumed.
755 -C, --directory=DIR
757 Change to DIR before performing any operations. This option is
758 order-sensitive, i.e. it affects all options that follow.
759 --exclude=PATTERN
761 Exclude files matching PATTERN, a glob(3)-style wildcard pat‐
762 tern.
763 --exclude-backups
765 Exclude backup and lock files.
766 --exclude-caches
768 Exclude contents of directories containing file CACHEDIR.TAG,
769 except for the tag file itself.
770 --exclude-caches-all
772 Exclude directories containing file CACHEDIR.TAG and the file
773 itself.
774 --exclude-caches-under
776 Exclude everything under directories containing CACHEDIR.TAG
777 --exclude-ignore=FILE
779 Before dumping a directory, see if it contains FILE. If so,
780 read exclusion patterns from this file. The patterns affect
781 only the directory itself.
782 --exclude-ignore-recursive=FILE
784 Same as --exclude-ignore, except that patterns from FILE affect
785 both the directory and all its subdirectories.
786 --exclude-tag=FILE
788 Exclude contents of directories containing FILE, except for FILE
789 itself.
790 --exclude-tag-all=FILE
792 Exclude directories containing FILE.
793 --exclude-tag-under=FILE
795 Exclude everything under directories containing FILE.
796 --exclude-vcs
798 Exclude version control system directories.
799 --exclude-vcs-ignores
801 Exclude files that match patterns read from VCS-specific ignore
802 files. Supported files are: .cvsignore, .gitignore, .bzrignore,
803 and .hgignore.
804 -h, --dereference
806 Follow symlinks; archive and dump the files they point to.
807 --hard-dereference
809 Follow hard links; archive and dump the files they refer to.
810 -K, --starting-file=MEMBER
812 Begin at the given member in the archive.
813 --newer-mtime=DATE
815 Work on files whose data changed after the DATE. If DATE starts
816 with / or . it is taken to be a file name; the mtime of that
817 file is used as the date.
818 --no-null
820 Disable the effect of the previous --null option.
821 --no-recursion
823 Avoid descending automatically in directories.
824 --no-unquote
826 Do not unquote input file or member names.
827 --no-verbatim-files-from
829 Treat each line read from a file list as if it were supplied in
830 the command line. I.e., leading and trailing whitespace is re‐
831 moved and, if the resulting string begins with a dash, it is
832 treated as tar command line option.
833 This is the default behavior. The --no-verbatim-files-from op‐
835 tion is provided as a way to restore it after --verba‐
836 tim-files-from option.
837 This option is positional: it affects all --files-from options
839 that occur after it in, until --verbatim-files-from option or
840 end of line, whichever occurs first.
841 It is implied by the --no-null option.
843 --null Instruct subsequent -T options to read null-terminated names
845 verbatim (disables special handling of names that start with a
846 dash).
847 See also --verbatim-files-from.
849 -N, --newer=DATE, --after-date=DATE
851 Only store files newer than DATE. If DATE starts with / or . it
852 is taken to be a file name; the mtime of that file is used as
853 the date.
854 --one-file-system
856 Stay in local file system when creating archive.
857 -P, --absolute-names
859 Don't strip leading slashes from file names when creating ar‐
860 chives.
861 --recursion
863 Recurse into directories (default).
864 --suffix=STRING
866 Backup before removal, override usual suffix. Default suffix is
867 ~, unless overridden by environment variable SIMPLE_BACKUP_SUF‐
868 FIX.
869 -T, --files-from=FILE
871 Get names to extract or create from FILE.
872 Unless specified otherwise, the FILE must contain a list of
874 names separated by ASCII LF (i.e. one name per line). The names
875 read are handled the same way as command line arguments. They
876 undergo quote removal and word splitting, and any string that
877 starts with a - is handled as tar command line option.
878 If this behavior is undesirable, it can be turned off using the
880 --verbatim-files-from option.
881 The --null option instructs tar that the names in FILE are sepa‐
883 rated by ASCII NUL character, instead of LF. It is useful if
884 the list is generated by find(1) -print0 predicate.
885 --unquote
887 Unquote file or member names (default).
888 --verbatim-files-from
890 Treat each line obtained from a file list as a file name, even
891 if it starts with a dash. File lists are supplied with the
892 --files-from (-T) option. The default behavior is to handle
893 names supplied in file lists as if they were typed in the com‐
894 mand line, i.e. any names starting with a dash are treated as
895 tar options. The --verbatim-files-from option disables this be‐
896 havior.
897 This option affects all --files-from options that occur after it
899 in the command line. Its effect is reverted by the --no-verba‐
900 tim-files-from} option.
901 This option is implied by the --null option.
903 See also --add-file.
905 -X, --exclude-from=FILE
907 Exclude files matching patterns listed in FILE.
908 File name transformations
910 --strip-components=NUMBER
911 Strip NUMBER leading components from file names on extraction.
912 --transform=EXPRESSION, --xform=EXPRESSION
914 Use sed replace EXPRESSION to transform file names.
915 File name matching options
917 These options affect both exclude and include patterns.
918 --anchored
920 Patterns match file name start.
921 --ignore-case
923 Ignore case.
924 --no-anchored
926 Patterns match after any / (default for exclusion).
927 --no-ignore-case
929 Case sensitive matching (default).
930 --no-wildcards
932 Verbatim string matching.
933 --no-wildcards-match-slash
935 Wildcards do not match /.
936 --wildcards
938 Use wildcards (default for exclusion).
939 --wildcards-match-slash
941 Wildcards match / (default for exclusion).
942 Informative output
944 --checkpoint[=N]
945 Display progress messages every Nth record (default 10).
946 --checkpoint-action=ACTION
948 Run ACTION on each checkpoint.
949 --clamp-mtime
951 Only set time when the file is more recent than what was given
952 with --mtime.
953 --full-time
955 Print file time to its full resolution.
956 --index-file=FILE
958 Send verbose output to FILE.
959 -l, --check-links
961 Print a message if not all links are dumped.
962 --no-quote-chars=STRING
964 Disable quoting for characters from STRING.
965 --quote-chars=STRING
967 Additionally quote characters from STRING.
968 --quoting-style=STYLE
970 Set quoting style for file and member names. Valid values for
971 STYLE are literal, shell, shell-always, c, c-maybe, escape, lo‐
972 cale, clocale.
973 -R, --block-number
975 Show block number within archive with each message.
976 --show-omitted-dirs
978 When listing or extracting, list each directory that does not
979 match search criteria.
980 --show-transformed-names, --show-stored-names
982 Show file or archive names after transformation by --strip and
983 --transform options.
984 --totals[=SIGNAL]
986 Print total bytes after processing the archive. If SIGNAL is
987 given, print total bytes when this signal is delivered. Allowed
988 signals are: SIGHUP, SIGQUIT, SIGINT, SIGUSR1, and SIGUSR2. The
989 SIG prefix can be omitted.
990 --utc Print file modification times in UTC.
992 -v, --verbose
994 Verbosely list files processed. Each instance of this option on
995 the command line increases the verbosity level by one. The max‐
996 imum verbosity level is 3. For a detailed discussion of how
997 various verbosity levels affect tar's output, please refer to
998 GNU Tar Manual, subsection 2.5.1 "The --verbose Option".
999 --warning=KEYWORD
1001 Enable or disable warning messages identified by KEYWORD. The
1002 messages are suppressed if KEYWORD is prefixed with no- and en‐
1003 abled otherwise.
1004 Multiple --warning messages accumulate.
1006 Keywords controlling general tar operation:
1008 all Enable all warning messages. This is the default.
1010 none Disable all warning messages.
1012 filename-with-nuls
1014 "%s: file name read contains nul character"
1015 alone-zero-block
1017 "A lone zero block at %s"
1018 Keywords applicable for tar --create:
1020 cachedir
1022 "%s: contains a cache directory tag %s; %s"
1023 file-shrank
1025 "%s: File shrank by %s bytes; padding with zeros"
1026 xdev "%s: file is on a different filesystem; not dumped"
1028 file-ignored
1030 "%s: Unknown file type; file ignored"
1031 "%s: socket ignored"
1032 "%s: door ignored"
1033 file-unchanged
1035 "%s: file is unchanged; not dumped"
1036 ignore-archive
1038 "%s: file is the archive; not dumped"
1039 file-removed
1041 "%s: File removed before we read it"
1042 file-changed
1044 "%s: file changed as we read it"
1045 failed-read
1047 Suppresses warnings about unreadable files or directo‐
1048 ries. This keyword applies only if used together with the
1049 --ignore-failed-read option.
1050 Keywords applicable for tar --extract:
1052 existing-file
1054 "%s: skipping existing file"
1055 timestamp
1057 "%s: implausibly old time stamp %s"
1058 "%s: time stamp %s is %s s in the future"
1059 contiguous-cast
1061 "Extracting contiguous files as regular files"
1062 symlink-cast
1064 "Attempting extraction of symbolic links as hard links"
1065 unknown-cast
1067 "%s: Unknown file type '%c', extracted as normal file"
1068 ignore-newer
1070 "Current %s is newer or same age"
1071 unknown-keyword
1073 "Ignoring unknown extended header keyword '%s'"
1074 decompress-program
1076 Controls verbose description of failures occurring when
1077 trying to run alternative decompressor programs. This
1078 warning is disabled by default (unless --verbose is
1079 used). A common example of what you can get when using
1080 this warning is:
1081 $ tar --warning=decompress-program -x -f archive.Z
1083 tar (child): cannot run compress: No such file or directory
1084 tar (child): trying gzip
1085 This means that tar first tried to decompress archive.Z
1087 using compress, and, when that failed, switched to gzip.
1088 record-size
1090 "Record size = %lu blocks"
1091 Keywords controlling incremental extraction:
1093 rename-directory
1095 "%s: Directory has been renamed from %s"
1096 "%s: Directory has been renamed"
1097 new-directory
1099 "%s: Directory is new"
1100 xdev "%s: directory is on a different device: not purging"
1102 bad-dumpdir
1104 "Malformed dumpdir: 'X' never used"
1105 -w, --interactive, --confirmation
1107 Ask for confirmation for every action.
1108 Compatibility options
1110 -o When creating, same as --old-archive. When extracting, same as
1111 --no-same-owner.
1112 Size suffixes
1114 Suffix Units Byte Equivalent
1115 b Blocks SIZE x 512
1116 B Kilobytes SIZE x 1024
1117 c Bytes SIZE
1118 G Gigabytes SIZE x 1024^3
1119 K Kilobytes SIZE x 1024
1120 k Kilobytes SIZE x 1024
1121 M Megabytes SIZE x 1024^2
1122 P Petabytes SIZE x 1024^5
1123 T Terabytes SIZE x 1024^4
1124 w Words SIZE x 2
1125
1127 Tar exit code indicates whether it was able to successfully perform the
1128 requested operation, and if not, what kind of error occurred.
1129 0 Successful termination.
1131 1 Some files differ. If tar was invoked with the --compare
1133 (--diff, -d) command line option, this means that some files in
1134 the archive differ from their disk counterparts. If tar was
1135 given one of the --create, --append or --update options, this
1136 exit code means that some files were changed while being
1137 archived and so the resulting archive does not contain the exact
1138 copy of the file set.
1139 2 Fatal error. This means that some fatal, unrecoverable error
1141 occurred.
1142 If a subprocess that had been invoked by tar exited with a nonzero exit
1144 code, tar itself exits with that code as well. This can happen, for
1145 example, if a compression option (e.g. -z) was used and the external
1146 compressor program failed. Another example is rmt failure during
1147 backup to a remote device.
1148
1150 bzip2(1), compress(1), gzip(1), lzma(1), lzop(1), rmt(8), symlink(7),
1151 xz(1), zstd(1).
1152 Complete tar manual: run info tar or use emacs(1) info mode to read it.
1154 Online copies of GNU tar documentation in various formats can be found
1156 at:
1157 http://www.gnu.org/software/tar/manual
1159
1161 Report bugs to <bug-tar@gnu.org>.
1162
1164 Copyright © 2013-2019 Free Software Foundation, Inc.
1165 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li‐
1166 censes/gpl.html>
1167 This is free software: you are free to change and redistribute it.
1168 There is NO WARRANTY, to the extent permitted by law.
1169TAR July 13, 2020 TAR(1)