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